Creating a Request

A request is a call for a specific resource. The client provides the server with information about the desired resource and the action to perform on that resource. When the server receives the request, it performs an action based on the properties of the request and returns a response to the client. See Receiving a Response for additional information.

A REST API request consists of four components:

 

Component

Description

Example

Uniform Resource Locator (URL)

The location of a specific resource.

https://{application-server}/CGRestAPI/api/IncidentRequest

Method

The action to perform on the resource.

Note: The REST API only supports the GET, POST, PUT, and DELETE methods.

POST

Headers

Additional metadata required by the server before it can process the request.

sessionid: 46l8Xd/xkIVx1QQNvj2SoQ==

Content

The JavaScript Object Notation (JSON)-as body or payload for the request, if required.

{
     "username": "administrator",
     "password": "abcd1234"
}

 

Resources

Resources define the items or entities in the application that are affected by the request. Resources are exposed through the REST API using Uniform Resource Identifiers (URL), which specify the logical location of resources on the server. The client needs to know the URL in order to access the correct resource.

Tip: There is often confusion between Universal Resource Identifiers (URIs) and Universal Resource Locators (URLs). URIs define the location of a resource, but they don't necessarily need to specify the protocol used to access the resource. A URL is a type of URI that specifies the protocol in addition to the location. Technically the REST API uses URLs, since you need to specify either the HTTP or HTTPS protocol when accessing a resource.

For example, the following URL lets you retrieve information about an incident request from a ChangeGear server. It consists of:

  • The base URL that defines where the REST API is located

  • An entity specifier (required when using the GET or DELETE methods)

  • The type of entity (or resource) being accessed

  • The unique identifier of the entity (or resource) being accessed. In this case, we are accessing the incident request with an ID of 4.

     

 

Note: A URL may have additional components depending on the resource being accessed. These components are explained in more detail for each API endpoint.

Parameters

Some REST API calls require you to specify parameters as part of the URL. Parameters are additional values appended to the URL that further identify the resource being requested or updated. In the URL shown above, IncidentRequest and 4 are parameters that specify the type and the unique identifier of the entity being retrieved. Other parameters allow you to retrieve more detailed information about a resource, pass data values, and even filter the contents of the server's response.

Percent-Encoding

In some cases, you may need to pass a value in the URL that contains special characters, such as spaces or symbols. To ensure the REST API can process the URL, use percent-encoding (also known as URL encoding) to replace special characters with their properly-encoded equivalent. Percent-encoding is especially important when passing user-defined strings in the URL, such as a search string.

Percent-encoding is defined in detail by the Internet Engineering Task Force (IETF) in RFC 3986 Section 2.1.

Methods

Methods define the action to perform on the resource. The REST API supports four methods:

  • GET - Retrieves information about a specific resource.

  • POST - Creates a new resource.

  • PUT - Updates an existing resource.

  • DELETE - Deletes a resource.

For example, in order to retrieve information about all incidents in the system, we would construct a request with the following properties:

  • URL: https://changegear-server/CGRestAPI/api/entity/IncidentRequest

  • Method: GET

  • Content Type: JSON

    Note: The REST API communicates using JavaScript Object Notation (JSON), a simple and standardized format for transmitting data. When submitting a request, be sure to specify JSON as the content type.

 

Headers

Headers contain any metadata required by the application server before it will process a request. For most requests, the REST API only requires you to pass a valid session ID in the header. The header also defines the content type of the request, which is JSON. All requests must be authenticated. You can use the following methods to authenticate and/or obtain your session ID.

 

Body

The body of the request contains the data that will be supplied to the system when the request is processed. Once the request has been validated by the REST API, the body contains the information about the object being accessed or modified. For all REST API requests, the request body takes the form of a JSON object.