Getting started

Getting access to the REST API

To be able to create API keys your APSIS Pro account needs to be configured to get access to the REST API. (contact APSIS at info@apsis.com or +46 (0)40 24 97 70 to place an order for the API, or if you have any questions regarding access to the API).

Creating an API Key

Each API call has to include an API key. This key is a unique string that identifies the APSIS Pro account that is using the API, and defines what data the caller has the right to access. To get an API key, log in to your APSIS Pro account and enter the Account section. Find the API Keys link and click to generate a new API key. One account can have multiple API keys and you manage your keys via the Account Settings section in APSIS Pro.

Using an API Key

The API uses HTTP basic authentication as its authentication mechanism where the username is set to the API key and the password is empty. The format for an API request is

http://API_KEY:@API_METHOD_URL

where "API_KEY" is your key and "API_METHOD_URL" is the URL to the API method you are calling. There is no password used for the HTTP Basic authentication, so make sure that there is no space between the ":" (colon) and the "@" (at sign).

For example, a call with the API key "abc123" to the CreateMailingList method looks like this:

http://abc123:@se.api.anpdm.com/v1/mailinglists/

The API is available through HTTPS via https://se.api.anpdm.com:8443

It is also possible to send the authentication in the "Authorization" HTTP Header. This is done by sending a base 64 encoded string that consists of "username:password", in Apsis case this means "key:" (i.e. no password is used and the API key as username).

For example if the API key is "abc123" the base 64 encoded string would be "YWJjMTIzOg==" and the header would be:

Authorization: Basic YWJjMTIzOg==

Code and HTTP Status Code

The "code" in the API response contains a status of how the API request went. In addition to the code in the content, the HTTP Status Code is also set to reflect the status of the request. These are the codes and HTTP Status Codes the APSIS API will return:

State Code Description
1 200 OK - successful API request
-1 500 Internal Server Error - there was an issue with the API server. Contact APSIS support with the request details to get this resolved.
-2 400 Validation Error - One or more parameters in the request are invalid
-3 404 Not Found - the URL is incorrect and no API method is found to deal with the request
-4 401 Unauthorized - lack of access rights to perform the API request, for example using an invalid API key
-5 503 Busy - the API server is currently not available
-6 503 API Disabled - the API service is temporarily offline for maintenance and not available at the moment.
-7 503 Bad Request - the request is badly formatted
-8 405 Method not allowed - the API method is not allowed for given request


It is best practice to be able to handle all these response codes.

Message

The message is a status description meant for human consumption, and usually contains more details than the code. If something went wrong this message is helpful in debugging the issue.

Security

It is highly recommended that the usage of the API is limited to HTTPS only. Using HTTPS will ensure that all the API communication is SSL encrypted. Not using HTTPS means that your API calls and your API key could potentially be stolen and misused. For the same reason it is important to keep the API keys secure and to change them if you suspect any leak of a key. The API uses port 8443 for SSL encrypted traffic, hence the HTTPS URL is https://se.api.anpdm.com:8443/