Previous topic

Message Formats

Next topic

HTTP Responses

DOCUMENTATION
Last updated 28-Jun-2016

HTTP Headers

In APS infrastructure, special APS headers are used in addition to the set of standard HTTP headers .

../../../../_images/aps-headers.png
HEADER Sender Recipient Requirements
APS-Token APS UI APS Controller Mandatory in each REST request
APS-Controller-URI APS Controller APS App Instance Mandatory in each REST request
APS-Identity-ID APS Controller APS App Instance Mandatory in each REST request forwarded from APS UI
APS-Application-ID APS Controller APS App Instance When one application sends request to another application, the APS Controller sends the source APS App Instance ID to the target APS App Instance.
APS-Instance-ID APS Controller APS App Instance Mandatory in each REST request and used by the APS controller to address a request to a certain APS application instance. The header identifies the receiver application instance.
APS-Transaction-ID
APS Controller

APS App Instance
APS App Instance

APS Controller
APS Controller always sends it to the target APS App Instance.
APS App Instance may send it to specify the transaction.
APS-Request-Phase APS Controller APS App Instance In a provisioning request, the APS Controller specifies if the provisioning mode is sync or async
APS-Info APS App Instance APS Controller In an async provisioning operation, the APS application instance sends the description of the task that must be scheduled in Operations Automation to verify if the provisioning is completed
APS-Retry-Timeout APS App Instance APS Controller In an async provisioning operation, the APS application instance defines the period of the task that must be scheduled in Operations Automation to verify if the provisioning is completed
APS-Resource-ID APS App Instance APS Controller Applications may use it for impersonation

Note

Please be aware that most of the headers are skipped in the examples and in other articles of this specification to save space.

Below is detailed description of each HTTP header.

APS-Token

An APS token is originated by the authentication authority of the Hosting Platform for a certain user. A user who passes authentication against the authority and holds the token should pass it when sending a REST request to the APS controller. For example, a GET request may look as follows:

GET /aps/2/resources/
APS-Token: ewogICAgIC ... p9Cg==
...

The APS controller uses the token to authenticate and authorize the operation requested by the user.

Note

Tokens are never passed to APS application endpoints.

APS-Controller-URI

APS controller always sends the URI that the recipient should use for addressing its requests or responses to:

GET /aps/2/resources/
APS-Controller-URI: https://apsc-domain-name/
...

APS-Identity-ID

APS controller sends the APS identity ID of the hosted service user (HSU) or customer administrator (staff member) to allow applications to identify who is requesting an operation. When a user logs in to the control panel (CP) of the hosting platform, the CP gets the user token. Application UI sends this token when requesting the APS controller for a CRUD or custom operation. APS controller uses the token to get the user ID from the hosting platform. In Odin Service Automation, a user ID is respectively a hsuID or a staffMemberID.

../../../../_images/aps-identity.png

Note

In Service Automation, this feature is enabled for the provider CP and reseller CP since version 6.0. For customer CP and service user CP (MyCP), it works since version 5.5.

APS controller does not send the APS-Identity-ID header to an application in the following cases:

  • A request is received from an application impersonating an account.
  • A received request contains a vendor anonymous token.

APS-Application-ID

Each APS application instance gets its unique ID when the APS controller sets the SSL authentication environment for this instance.

When an APS application calls another application through the APS controller, the latter finds the APS application instance ID in the SSL client certificate. Then the APS controller forwards the request to the destination APS application endpoint and assigns the caller ID to the APS-Application-ID header.

The header allows the receiver to identify the source APS application instance, i.e. the caller.

POST /wordpress/
APS-Application-ID: f1b8b168-6446-478d-afdf-d46505314e97
...

APS-Instance-ID

Each APS application instance gets its unique ID when the APS controller sets the SSL authentication environment for this instance.

When the APS controller sends a REST request to an APS application endpoint, it specifies the APS application instance by means of the APS-Identity-ID header that contains the instance ID. This allows an APS application endpoint to serve several APS application instances differentiating them by their unique ID.

POST /wordpress/
APS-Instance-ID: bd2178c7-b46f-4dab-83e6-90f5c9c952a9
...

APS-Transaction-ID

This is an identifier of a business transaction (workflow ID) initiated by the APS controller. The controller will send the header to an APS application endpoint in requests that are parts of the same business process. For example, it is used for creation of an application resource that requires creation of other resources in the same transaction.

The application should send back the header to the controller if it wants to include the requested operation into a business process. Also, this header allows the application to get additional visibility of resources being modified or created during the business process.

For example, while processing a resource provisioning request, the application decides to subscribe to an event by using the Subscribing to Events request.

In this case, it should send back the APS-Transaction-ID header, which it has got together with the resource provisioning request.

POST /aps/2/resources/
APS-Transaction-ID: 5586-37
...

The header is always originated by the APS controller and used by applications to connect back to the controller with sub-requests.

APS-Request-Phase

When sending a request for provisioning, the APS controller uses this header to define if the provisioning phase is synchronous, APS-Request-Phase: sync, or asynchronous, APS-Request-Phase: async. In its initial request, the APS controller always requires the sync phase. The application can accept it or propose the async mode by sending the HTTP/1.1 202 Accepted response with APS-Info and APS-Retry-Timeout headers as described at Asynchronous Provisioning. In its subsequent requests, the APS controller will use the APS-Request-Phase: async header until the provisioning is completed or failed.

POST /vpscloud/vpses/
APS-Request-Phase: async

{ /* request body */ }

APS-Info

When sending the HTTP/1.1 202 Accepted response to propose the async phase, the application also adds this header containing description of a periodical task that the APS controller must schedule. This is also described at Asynchronous Provisioning.

APS-Retry-Timeout

When sending the HTTP/1.1 202 Accepted response to propose the async phase, the application also adds this header containing period of a periodical task that the APS controller must schedule. This is also described at Asynchronous Provisioning.

APS-Resource-ID

When an APS application instance sends a request to the APS controller, it may imitate credentials of a client. Therefore, in its header, it sends the ID of any of its resources provisioned for the client.

POST /wordpress/
APS-Resource-ID: A3FA6483-F40A-4240-AF16-FB8314328477
...

Content-Range

In cases, when the APS controller returns an array of objects, it responds with the Content-Range header to indicate how many items are being returned and how many total items exist.

RFC 2616 defines the Content-Range header that allows different implementations of HTTP/1.1 to specify any range units in addition to bytes specified in HTTP/1.1:

3.12 Range Units

HTTP/1.1 allows a client to request that only part (a range of) the
response entity be included within the response. HTTP/1.1 uses range units in the Range (section 14.35)
and Content-Range (section 14.16) header fields. An entity can be broken down into subranges
according to various structural units.

range-unit       = bytes-unit | other-range-unit
bytes-unit       = "bytes"
other-range-unit = token

The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
implementations MAY ignore ranges specified using other units.

APS extends the range units with the “items” token specified in an HTTP/1.1 compatible manner:

HTTP/1.1 200 OK
Content-Range: items <FIRST>-<LAST>/<TOTAL>
...
  • <FIRST> - absolute position of the first item in the returned range.
  • <LAST> - absolute position of the last item in the returned range.
  • <TOTAL> - total number of items at the moment when the response was generated.