REST API Reference

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 complex
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 json
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 false
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.

JSON Representation

{
	"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.

Child pages