Welcome to Apex REST API. To use the API, you'll need to be familiar with REST, as well as the following information. Take a moment to review this page before diving into the REST calls. To understand the API you will be using before developing your applications, you can go to the API documentation page to read the API document and actually test run it there.
Apex API uses industry standard OpenID Connect extension of OAuth 2.0 to authorize calls. Either client_credential or password types can be used as the grant type used for authorization. There are three steps involved in order to make a call to Apex RESTful API:
Apex will register API client application on behalf of API client. Apex will provide client ID and client secret after API client application registration is completed. There are two sets of client ID and client secret. One set is for sandbox testing and one set is for production. API client application must use client ID and client secret to request access token. Client ID and client secret are considered confidential information, therefore must be protected by both Apex and API client.
API client application must request access token from token end point (implemented using OpenID Connect access token standard) using client ID and client secret. As defined by OpenID Connect specification, access token will expire after certain time. API Client application must handle token expiration and request a new access token after receiving token expiration response. API client can request multiple access tokens, but it is recommended to share access tokens if possible. The access token type is Bearer token type and must be specified in HTTP Authorization header along with access token.
Token expired or revoked sample response:
HTTP/1.1 401 Unauthorized Server: Apache-Coyote/1.1 WWW-Authenticate: Bearer error="invalid_token",realm="localhost" Content-Length: 0 Date: Tue, 05 May 2015 15:40:46 GMT
API Client application must include an access token in each call to Apex RESTful API. Access token must be included in HTTP Authorization header in following format: Authorization: Bearer {access token}
For example:
Authorization: Bearer 96da62fe-9144-3d18-a480-bde90112fcc0...
A response to HTTP GET may sometimes include much information and it needs to be split into several responses. Each response is called a paging result. Paging results are related through paging meta data in URIs.
In order to make it easy for API clients, API returns meta data to specify the navigation when paging results are returned. Paging meta data includes a list of hypermedia links for previous page, next page, first page and last page links when they are applicable. The first paging result does not have a previous page link and the last paging result doesn't have a next page link.
Here are a couple of examples explaining paging meta data format in APIs. The first example shows a default page size of 20 records per page. The second example shows a client specified page size of 30 records.
Example 1:
{
"totalPages": 32,
"totalElements": 640,
"links": [
{
"rel": "prev",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=1&size=20"
},
{
"rel": "next",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=3&size=20"
},
{
"rel": "first",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=0&size=20"
},
{
"rel": "last",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=31&size=20"
}
]
}
Example 2:
{
"totalPages": 22,
"totalElements": 640,
"links": [
{
"rel": "prev",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=1&size=30"
},
{
"rel": "next",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=3&size=30"
},
{
"rel": "first",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=0&size=30"
},
{
"rel": "last",
"mediaType": "application/json",
"href": "https://1800.apexsupplychain.com/accountapi/v1.0/accounts?page=21&size=30"
}
]
}
where
GET /accounts/100100100 - Interpreted as "Query the account 100100100 where 100100100 is the account's entity number"
GET /accounts?name=prod - Interpreted as "Query the account whose name is prod" GET /accounts?size=36 - Interpreted as "Query all accounts with a page size of 36."All search parameters in exact match are case in-sensitive.
GET /companies?alike=name&name=Apex - Interpreted as "Query companies whose name includes the word Apex" - As a result company like "Apex Supplychain", "Mason Apex" and "East Apex Mason" all meet the query criteria.
Apex REST API supports HTTPS only. Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request. Apex REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.
In the request body, the APIs attempt to convert supplied data to the correct type if possible. This includes conversion between strings and numbers so for Boolean values true is equivalent to a non zero number and false is equivalent to 0.
The HTTP response includes: