Getting Started RestClient 3.x

The Simplest Example

RESTClient is a class that represents the server that is hosting the resources you want to work with. Usually, this would just be a protocol, host and optional port.

var client = new RESTClient("http://localhost:1234");

However, if all of your resources are accessed from a common path entry point, then it would make sense to add that to the base URL you pass to the constructor as well.

var client = new RESTClient("http://localhost:1234/services");

From there, if you need to provide any access credentials to the client, you can do that by using the Credentials property.

client.Credentials = new NetworkCredential("username", "password");

Likewise, you can interact with the cookies sent to and received from this client via the Cookies property.

var cookie = new Cookie("sessionid", "A113");
client.Cookies.Add(cookie);

And now you have a working client! From here, all you do is call the Execute() method and pass it a RESTRequest, and it will return a RESTResponse. Easy peasy, rice and cheesy.

RESTRequest

A RESTRequest represents a resource you want to interact with and a method of interacting with it. The resource itself is agnostic with respect to the client it is executed on, as you will pass the request to a client for execution.

RESTRequest has a named and optional argument constructor. Every argument is named, and every argument is optional. Pass it something, or pass it nothing.

var request = new RESTRequest("/user/{id}");

The string passed in gets assigned to the Resource public property. Notice that I can put placeholders into the Resource by containing them inside curly braces, so it can be used over and over again! Values for the placeholder can be provided via the AddParameter method.

request.AddParameter("id", "1234");

Notice how the value inside the curly braces of my Resource string matches the first parameter passed to the AddParameter method. That is important, as it won't give you an error if you try to add parameters for which no placeholder exists - so watch your spelling. Those parameters will simply be ignored when building the PathInfo.

Speaking of which, if you try to get the PathInfo property while there are still placeholders in your Resource for which parameters have not been provided, a ClientStateException is thrown.

Automatic Clearing of Parameters

Be aware that there are two scenarios in which all parameter values get cleared, and you will need to redefine them as necessary. Those scenarios are:

1. After the request is executed by a client, regardless of what response was returned
2. When the Resource property is modified

So if we changed our Resource from above thusly:

request.Resource = "/person/{id}";
request.AddParameter("id", "1234");

We will need call AddParameter again, even if the placeholder key and the desired value do not change.

Other Request Properties

You can modify the HTTPMethod via the Method property.

request.Method = HttpMethod.GET;

You can change the content type of the payload (if any) to suite your needs.

request.ContentType = ContentType.JSON;
request.Payload = "{\"key\":\"value\"}";

And even add key/value pairs to the query string.

request.AddQuery("index", "55");

If you want it to wait more than 2000 milliseconds for a response, change the timeout value!

request.Timeout = 1210; //1.21 seconds!

If you want to change the default value globally from 2000 milliseconds to a different value, use the static RESTRequest.GlobalTimeout property.

Finally, you can control the headers sent with the request. Add standard or custom headers the same way.

request.Headers.Add(HttpRequestHeader.CacheControl, "no-store, must-revalidate");
request.Headers.Add("Hodor", "Hodor");

And your request is ready to be executed! Release the Kraken!

RESTResponse

You can only get a RESTResponse as a return value from the Execute() method of the RESTClient.

var response = client.Execute(request);

The response contains lot of useful information, including the response content.

In addition to providing the response, when the Execute method is called, the client cookies are updated and the Reset method is called on the request.

Profit!!!!

And there you have it, folks! Be your own rest client!