Fetching data

The Operator API has been built according to JSON:API specifications and supports common features such as data sorting, filtering and sparse fieldsets. The following section contains general information taken from JSON:API specifications and is intended to be used as a quick reference on how certain Operator API features work and should be used.

If you are not familiar with JSON specifications, please review them at the official JSON:API website before building your first application using the Operator API.

Inclusion of related resources

Some endpoints support an include request parameter to allow the client to customise which related resources should be returned.

• If an endpoint does not support the include parameter, it will respond with 400 Bad Request to any requests that include that endpoint.

• If an endpoint supports the include parameter and a client supplies it, the server will not include unrequested resource objects in the included section of the compound document.

Important

Some endpoints return resources related to the primary data by default.

The value of the included parameter must be a comma-separated (U+002C COMMA, “,”) list of relationship paths. Multiple related resources can be requested in the comma-separated list.

Below is an example of retrieving a list of routes, with gateway and customer relationships included:

GET

/api/rest/public/operator/termination_routes?include=gateway,customer

http

GET /api/rest/public/operator/termination_routes?include=gateway%2Ccustomer HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/termination_routes?include=gateway%2Ccustomer' -H "Content-Type: application/vnd.api+json" --user username:password

Sparse fieldsets

A client may request that an endpoint return only specific fields in the response on a per-type basis, by including a fields[TYPE] parameter in the request URL.

The value of the fields parameter must be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned.

If a client requests a restricted set of fields for a given resource type, an endpoint will not include additional fields in the resource objects of that type in its response.

An example of retrieving a list of gateways specifying host and name attributes is shown below:

GET

/api/rest/public/operator/termination_gateways?fields[termination_gateways]=host,name

http

GET /api/rest/public/operator/termination_gateways?fields%5Btermination_gateways%5D=host%2Cname HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/termination_gateways?fields%5Btermination_gateways%5D=host%2Cname' -H "Content-Type: application/vnd.api+json" --user username:password

Important

In this example, the URI is shown in unencoded [ and ] characters for simpler readability. In practice, these characters must be percent-encoded, as per the requirements in RFC 3986.

Important

This section applies to any endpoint that responds with resources as primary or included data, regardless of the request type. For instance, a server may support sparse fieldsets along with a POST request to create a resource.

Sorting

Most Operator API endpoints support requests to sort the primary data with a sort query parameter. The value for sort must represent sort fields.

An example of sorting customers by a capacity limit attribute is show below:

GET

/api/rest/public/operator/customers?sort=capacity_limit

http

GET /api/rest/public/operator/customers?sort=capacity_limit HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/customers?sort=capacity_limit' -H "Content-Type: application/vnd.api+json" --user username:password

Multiple sort fields can be included by allowing comma-separated (U+002C COMMA, “,”) sort fields. Sort fields should be applied in the order specified.

An example of sorting customers by the capacity limit and SIP account limit is show below:

GET

/api/rest/public/operator/customers?sort=capacity_limit,sip_account_limit

http

GET /api/rest/public/operator/customers?sort=capacity_limit%2Csip_account_limit HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/customers?sort=capacity_limit%2Csip_account_limit' -H "Content-Type: application/vnd.api+json" --user username:password

The sort order for each sort field will be ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“). In such a case, results will be sorted in descending order.

An example of sorting Customer by capacity limit in descending order is show below:

GET

/api/rest/public/operator/customers?sort=-capacity_limit

http

GET /api/rest/public/operator/customers?sort=-capacity_limit HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/customers?sort=-capacity_limit' -H "Content-Type: application/vnd.api+json" --user username:password

This example will return customers with the highest capacity limit values first.

If the endpoint does not support sorting as specified in the query parameter sort, it will return 400 Bad Request.

The server may apply default sorting rules to top-level data if the request parameter sort is not specified.

Pagination

Some of the Operator API endpoints limit the number of resources returned in a response to a subset (“page”) of the whole set available. The API uses a page-based pagination strategy and supports the following query parameters:

• page[number]

• page[size]

Also, responses in some of the Operator API endpoints provide links to traverse a paginated data set (“pagination links”).Pagination links appear in the links object that corresponds to a collection.

The following keys are used for pagination links:

• first: the first page of data

• last: the last page of data

• prev: the previous page of data

• next: the next page of data

Keys will either be omitted or have a null value to indicate that a particular link is unavailable.

Concepts of order, as expressed in the naming of pagination links, remain consistent with JSON:API’s sorting rules.

Important

This section applies to any endpoint that responds with a resource collection as primary data, regardless of the request type.

Filtering

The filter query parameter is reserved for filtering data. Clients should use this key for filtering operations. Each Operator API endpoint has a different set of supported filters.

An example of filtering Termination Gateways by host “hello.com” is shown below:

GET

/api/rest/public/operator/termination_gateways?filter[host]=hello.com

http

GET /api/rest/public/operator/termination_gateways?filter%5Bhost%5D=hello.com HTTP/1.1
Host: api.telecom.center
Content-Type: application/vnd.api+json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

curl

curl -i -X GET 'https://api.telecom.center/api/rest/public/operator/termination_gateways?filter%5Bhost%5D=hello.com' -H "Content-Type: application/vnd.api+json" --user username:password