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-Account-Hierarchy	APS Controller	APS App Instance	A string containing comma-separated APS IDs of the provider, all subsidiary resellers, and a customer in a chain that leads from the provider to the customer.
APS-Actor-ID	APS Controller	APS App Instance	Specifies the security actor. Mandatory in each REST request forwarded through the APS controller when an actor can be identified.
APS-Actor-Scope	APS UI	APS Controller	The actor specifies the scope of resources related to the request
APS-Application-ID	APS Controller	APS App Instance	When one application sends a 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-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-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-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-Original-Identity-ID	APS Controller	APS App Instance	Used when the customer’s sales vendor logs in to the user panel impersonating the customer
APS-Resource-ID	APS App Instance	APS Controller	Applications may use it for impersonation
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 the platform to verify if the provisioning is completed
APS-Request-Phase	APS Controller	APS App Instance	In a provisioning request, the APS controller specifies whether the provisioning mode is sync or async
APS-Skip-Content-Range	APS UI	APS Controller	The sender requires the APS controller to avoid counting the total number of resources matching the request
APS-Subscription-ID	APS UI	APS Controller	The actor specifies the APS ID of the subscription related to the requested operation
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.

Note

Be aware that most of the headers are skipped in the examples and in other articles of this documentation to save space.

Below is a detailed description of each HTTP header.

APS-Account-Hierarchy

The HTTP APS-Account-Hierarchy header is a string containing comma-separated APS IDs of the provider, all subsidiary resellers, and a customer in the chain that leads from the provider to the customer. The APS controller sends this header when calling the exportRatedData operation on an APS connector side.

In the following example, the first APS ID belongs to the provider, then goes the customer’s parent reseller, and finally the customer itself.

“d257f87a-4bff-43ab-9ff7-11e217f3b93e, b3325a5f-3644-4d47-a936-0ec77c8e1e15, a3cab1f8-04b2-4ce6-a696-a956dd8f9071”

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-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 cases when a request is sent on behalf of a user or account (when it is sent from a user 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 their own resources or their own and 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 sales vendor for sale. This way, a reseller impersonates an anonymous buyer in the sales vendor’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

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-Application-ID

Each APS application instance gets a 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-Controller-URI

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

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

APS-Identity-ID

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

The APS controller does not send the APS-Identity-ID header to an application when a request is received from an application impersonating an account.

APS-Info

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

APS-Instance-ID

Each APS application instance gets a 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-Original-Identity-ID

This header is used only when the provider or reseller staff impersonates a customer by logging into the customer panel from the 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-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
...

APS-Retry-Timeout

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

APS-Request-Phase

When sending a request for provisioning, the APS controller uses this header to define whether 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-Skip-Content-Range

By default, 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 in accordance with the pagination rules. 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.

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> is the absolute position of the first item in the returned range.

• <LAST> is the absolute position of the last item in the returned range.

• <TOTAL> is the total number of items at the moment when the response was generated.

Counting the total number of resources is often not necessary but impacts platform performance. The APS-Skip-Content-Range header in a request requires the APS controller to avoid the calculation of the total number of resources and to omit the Content-Range header in its response:

GET /aps/2/resources
APS-Skip-Content-Range: true

Note

To get the total number of resources that match a certain RQL request, use the limit(0,0) function in the RQL request without the APS-Skip-Content-Range header. You will get the total number in the Content-Range 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 which subscription the required resource will be processed in.

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

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

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 sends the header back to the APS 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 sends 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 processes the APS-Transaction-ID header. It adds the header to all requests the application sends to the APS controller.

← Session Management

Message Formats →