REST API by Category
REST API Alphabetical List
API Common Request Parameters
The below table lists the general request parameters that can be sent with all requests.
Name | Description | Required | Default | Possible Values |
---|---|---|---|---|
apsws.time | A UNIX timestamp denoting the current time when the request is issued. | Yes |
| UNIX timestamp |
apsws.authMode | Specifies the type of signature passed in the request. | No | complex | simple |
apsws.authSig | Represents the signature of the request. Optionally, a user request can be signed with a token. | No |
| Refer to "Request Authentication section" |
apsws.responseType | Specifies the format of the response of the current request. | No | xml | xml |
apsws.id | The user or device issuing the current request. If not specified, then it is assumed that the request is issued by the owner. | No |
| The login of a user or the id of a device. |
apsdb.runAs | Allows an owner to issue a request as if he was the specified user. | No |
| The login of a user. |
apsws.jc | Specifies the name of a client side javascript function to be executed upon completion of the current request. The response of the request will be passed as the only parameter of this callback function. | No |
|
|
apsdb.redirHref | Specifies the url to redirect the client upon completion of the request. It sets the window.name to the response of the request. It requires the apsdb.callback request parameter. | No |
|
|
apsdb.callback | This parameter is required when the apsdb.redirHref is sent to the request. It passes the parameter called "callback" to the redirected page and sets its value to the value of this request parameter. | Conditional |
|
|
apsdb.force200ResponseStatus | Controls whether or not the response status is set to 200 upon failure. | No | false | true |
apsws.customField | A request parameter that may contain any data that will not be processed by apstrata. It can be used to send data to third party services. | No |
|
|
API Common Response Elements
The following is a JSON representation of the response elements that are common to all APIs. The XML representation follows the same structure; however, for the sake of documentation, we will be using the JSON response format.
{ "response": { "metadata": { "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "success | failure", "errorCode": "Logical Error Code", "errorDetail": "Logical Error Message", "statusCode": "HTTP Response Code" } } }
The "response" element is the root one for all responses. The "metadata" element is also a common one with the following info:
- requestId: A unique identifier for each request
- status: Indicates whether the request succeeded or failed. The possible values are "success" or "failure".
- errorCode: Error code identifying a logical error; this element is returned only in the case of a logical error; refer to each API for specific error codes.
- errorDetail: Error message describing a logical error; this element is returned only in the case of a logical error; refer to each API for specific error messages.
- statusCode: HTTP response code, such as 200 for success.
API Common Logical Error Codes
The below table lists the logical errors that are common to all APIs.
Error Code | Error Description |
---|---|
ACCOUNT_SUSPENDED | The account making the request is suspended. |
ACTION_REQUIRED | No action is sent in the request. |
AUTHENTICATION_KEY_REQUIRED | No authentication key is sent in the request. |
CALLBACK_MISSING | apsdb.redirectHref request parameter is specified without specifying apsdb.callback. |
DUPLICATE_PARAMETER_VALUE | Duplicate values are not allowed for specific request parameters. |
INVALID_ACTION | The action specified in the request is invalid. |
INVALID_PARAMETER | Invalid request parameter across all APIs. |
INVALID_REQUEST | The request is invalid (e.g.,) an owner asking for a token. |
INVALID_SIGNATURE | The signature specified is not valid. The account making the request is flagged as deleted. |
INVALID_TOKEN | The token specified in the request is invalid. |
INVALID_URI | Missing authentication key or action in the request. |
INVALID_USER | Invalid user signing the request. |
MALFORMED_REFERER | Invalid originating referrer. |
PERMISSION_DENIED | No permission to call a certain API. |
SIGNATURE_REQUIRED | No signature is sent in the request. |
TIMESTAMP_REQUIRED | No timestamp is sent in the request. |