$Rest¶

Allows interaction with REST services using JSON or XML content types.

REST service operations involve the following objects: RestClient, RestRequest, and RestResponse.

1	`const $Rest: Rest;`

Remarks¶

Creating a REST Client
To create a client, use the $Rest.Create method, providing the REST service's base URL via the RestRequest.Url property.

Example¶

var client = $Rest.Create('http://api.geonames.org/');

Authenticating a REST Client Some REST services require authentication. eMakina supports OpenAuth2-based authentication. To create an authenticated client, specify the service and identity as shown below. This method acquires an authentication token from the service and ensures the client is authenticated. If the token cannot be acquired from the service, the

RestClient.EnsureAuthenticated

method throws a JavaScript exception. You can also use the

RestClient.IsAuthenticated

property and the

RestClient.Authenticate

method to perform the same operation without error handling.

Example¶

var client = $Rest.Create('https://graph.microsoft.com/v1.0/', 'Office365', '', $WorkItem.CompletedBy).EnsureAuthenticated();

Creating a REST Request After creating the client connection, you can create a REST request and populate parameters as shown below.

Example¶

var request = client.Request('childrenJSON')
                .AddQueryParameter('username', 'demo')
                .AddQueryParameter('geonameId', id);

Every request created with a resource URL address is appended to the client's base URL. The request URL may contain parameters to build a dynamic URL address, as shown with the

sitePath

parameter below.

Example¶

var request = client.Request("sites/{sitePath}/drives")
                .AddUrlParameter("sitePath", sitePath)
                .AddQueryParameter("$select", "id,name");

Populating a REST Request You can also set HTTP headers using the

RestRequest.AddHeader

method. Some REST methods require a JSON or XML-based body. You can specify the content of the request using the

RestRequest.AddObject

or

RestRequest.AddXml

methods.

Fetching a REST Response After populating the request, you can call the

RestRequest.Execute

method to execute it and fetch the

RestResponse

object. The

Execute

method does not perform any error checking by default. To ensure the request was executed successfully, use the

RestRequest.Expect

method to specify the expected status code.

Example¶

var response = request.Execute();

if (response.StatusCode == "OK") {
    var val = response.GetHeader('X-Header');
    var obj = response.ToJson();
}

REST Request Methods You can also use the

,

,

,

, and

methods to call the service with the corresponding HTTP method. Alternatively, you can manually set the

RestRequest.Method

before executing the request.

If the service always returns JSON or XML, you can use the

RestRequest.ExecuteJson

or

RestRequest.ExecuteXml

methods to fetch the response as a JSON object or an XML node, respectively.

Example¶

var object = request.ExecuteJson();

// object.person.name;