$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;

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¶

1

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

Authenticating a REST Client Some REST services require authentication. Emakin supports OAuth2-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¶

1

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¶

1
2
3

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¶

1
2
3

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¶

1
2
3
4
5
6

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 RestRequest.Get, RestRequest.Delete, RestRequest.Put, RestRequest.Post, and RestRequest.Patch 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¶

1
2
3

var object = request.ExecuteJson();

// object.person.name;

Capabilities¶

Client Creation¶

• Rest.Create: Creates a new RestClient instance.