HTTP Headers

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

APS Headers

HEADER	Sender	Recipient	Requirements
APS-Subscription-ID	APS UI	APS Controller	The actor specifies a subscriptions related to the requested operation
APS-Actor-Scope	APS UI	APS Controller	The actor specifies a scope of resources related to the 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-Original-Identity-ID	APS Controller	APS App Instance	Used when a service vendor logs into CCP impersonating a customer
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. The header identifies the caller.
APS-Actor-ID	APS Controller	APS App Instance	Specifies the security actor. Mandatory in each REST request forwarded trough the APS controller when an actor can be identified.
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 the platform 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-Subscription-ID

In a provisioning operation, when there are alternative subscriptions, the APS UI runtime adds the header to a REST request to specify a subscription the required resource should be processed in.

POST /aps/2/resources/
APS-Subscription-ID: 2996055a- ... -3f6fd6eba268

{ "aps": { ... }, ... }

APS-Actor-Scope

The scope of resources available for a request depends on the Security Roles of the actor (requester) towards the resources. The APS-Actor-Scope header allows a requester to change that default behavior for the cases when a request is sent on behalf of a user or account, in other words when it is sent from a control panel or from an external system authenticated as a user. The main use case is sending a request from a reseller when the latter needs to specify a scope, for example, to see only own resources or also all resources of the subordinate accounts.

Depending on the assigned value, the header defines a scope as follows:

• OWN – (default for resellers) only resources owned by the actor.
• FULL – (default for customers) resources bound with the actor through any of the security roles - administrator, owner, or referrer.
• VENDOR_PUBLIC – only resources that are available as public and owned by the actor’s parent, for example, service plans and related resources exposed by the parent for sale. This way, an actor (reseller) impersonates an anonymous buyer in the parent’s marketplace.
• ACCOUNT <APS_ID> – all resources in the FULL scope of a subordinate account that the actor impersonates through the APS ID of that account. For example, a reseller impersonates its customer to retrieve the internal IDs of the customer’s payment methods.
• SERVICE_TEMPLATE <APS_ID> – similar to VENDOR_PUBLIC, but the scope is limited to one particular service template whose APS ID is specified in the header. For example, a reseller gets the parent’s resources included in the specified service template.

Note

1. The header can be used by APS applications only in the UX1 user panel.

2. By default, in UX1, when a reseller admin uses an application UI to operate some resources, the actor scope is limited by the reseller’s own resources and resources at the first subordinate level. The latter is presented by the resources of the direct customers and direct sub-resellers without drilling down the hierarchy. An application can change the scope by means of the considered HTTP header.

APS-Controller-URI

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

GET app-endpoint/service-id/
APS-Controller-URI: https://apsc-domain-name/
...

APS-Identity-ID

APS controller sends the APS identity ID of the service user or customer administrator (staff member) logged in a control panel to allow applications to identify who is requesting an operation. In the platform, a user ID is respectively a hsuID or a staffMemberID.

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.

APS-Original-Identity-ID

This header is used only when the provider or reseller staff impersonates a customer by logging into the customer control pane (CCP) from PCP or RCP. In this case, the APS controller assigns the staff member ID to the APS-Original-Identity-ID header and sends it in addition to the APS-Identity-ID header that contains the ID of the impersonated user.

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, that is the caller.

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

APS-Actor-ID

Having identified an actor, the APS controller identifies the security actor and then forwards the request to the addressed APS application instance adding the APS-Actor-ID header in accordance with the following rules:

• If the actor is a staff member (administrator), the account ID will be assigned to the header.
• If the actor is a service user, the user ID will be assigned.
• If the actor is an APS application, the APS application instance ID will be assigned.

Note

When an administrator impersonates a customer or a service user, the actor is the impersonated customer or user as specified by the Security Model. Respectively, the impersonated customer ID or user ID will be assigned to the APS-Actor-ID header.

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-Instance-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.

Note

If an application provisioning logic is based on the APS PHP framework the latter takes care of processing the APS-Transaction-ID header. It adds the header to all requests the application sends to the APS controller.

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. For this purpose, in its header, it sends the ID of any of its resources provisioned for the client as explained in the impersonation concepts and model security concepts sections .

POST /aps/2/resources/
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.

← Session Management

Message Formats →