Custom Headers

In Connect Common Object Model (CCOM) v1.4, the following custom headers have been implemented for the Connect REST API binding:

For related examples, see:

osvc-crest-api-access-token

This API access token identifies the current or existing connection to optimize QoS connection among other competing connections. It's an optional custom header, but omitting it may lead to degraded performance and errors, even if it seems to test well without it.

In the response of a REST API call, a value is returned for the osvc-crest-api-access-token response header. You must provide this value in the osvc-crest-api-access-token request header of the subsequent REST API call. For the first REST API call, the server generates the value for the osvc-crest-api-access-token response header.

Note:

  • Don't change the token value because any change in the token value causes an error.
  • Always pass the token from the response of the previous API call in the request of the subsequent API call.

osvc-crest-next-request-after

The osvc-crest-next-request-after value indicates the time (in milliseconds) that must elapse before you make the subsequent REST API call. The value of the osvc-crest-next-request-after header is greater than or equal to zero.

Note:

The value for osvc-crest-next-request-after custom header is in milliseconds.

OSvC-CREST-Application-Context

From CCOM v1.4 onwards, the custom OSvC-CREST-Application-Context HTTP header is required. Your request will fail with a 400 Bad Request error if you do not provide this header. You can use this header to add comments to REST API requests. The Application Context data is written to the papi_meters table.

Note:

The maximum length of the text is 40 characters. If you use more than 40 characters, then a Bad-Request error occurs.

Valid request example

The following is an example of a REST API call that returns all account records.

  • The value of osvc-crest-next-request-after custom header is zero
  • The server generates the value for the token: osvc-crest-api-access-token. As shown in this example, the server generates the value 557F571645B190000000000000000AKtQgv_~lP2e8oPo7aJsNg29gaGlGRWuLjTsyAGTsijW56+2iks= for this token. This value must be passed as the token value in the subsequent REST API call.

Request example

GET https://mysite.example.com/services/rest/connect/v1.4/accounts

Request header example

The following table lists the required request headers with sample values.

Header Value
OSvC-CREST-Application-Context

This is a valid request for account.

Authorization

Basic YXBpdXNlcjE6QXBpdXNlcjE=

Response example


{
    "items": [
        {
            "id": 1,
            "lookupName": "Administrator -",
            "links": [
                {
                    "rel": "canonical",
                    "href": " https://mysite.example.com/services/rest/connect/v1.4/accounts/1"
                }
            ]
        },
   ...
}

Response header example

The following table lists the response headers with sample values.

Header Value
connection

Keep-Alive

content-language

en-US

content-type

application/json

date

Wed, 30 Aug 2017 09:49:23 GMT

f5_do_compression

yes

keep-alive

timeout=15, max=98

osvc-crest-api-access-token

557F571645B190000000000000000AKtQgv_~lP2e8oPo7aJsNg29gaGlGRWuLjTsyAGTsijW56+2iks=

osvc-crest-next-request-after

0

osvcstatus

200

rnt-machine

40.30

rnt-time

D=1487703 t=1504086563072285

server

Apache

transfer-encoding

chunked

vary

Agent

Invalid request example

This example requests the data for the account with ID 2, but it has an invalid Application Context header:

Request example

GET https://mysite.example.com/services/rest/connect/v1.4/accounts/2

Request header example

The following table lists an invalid Application Context header:

Header Value

OSvC-CREST-Application-Context

This request for account 2 has too many characters.

Response to invalid request example

{
  "type": "https://mysite.example.com/services/rest/connect/exceptions/OSC-CREST-00025",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid Request: ApplicationContext maximum length exceeded; value 51 > 40;
    OSvC-CREST-Application-Context header",
  "instance": "https://mysite.example.com/services/rest/connect/v1.4/accounts/2",
  "o:errorCode": "OSC-CREST-00025"
}