Best practices

How to make an API request

The APSIS API is a REST style API, which means that all API requests are made via URLs over HTTP. This is similar to the way a web page is returned in a web browser when a certain URL is called. One great advantage of a REST API is that it is very easy to use from almost all programming languages and platforms.

The easiest way to learn how to make a specific API call is to read the documentation for the method you want to call, and then use the "Make a Test Request" functionality in the documentation pages. That enables you to make an API request simply by filling in a form on a web page. T his enables you to see exactly how the request and the response looks.

In short, to make an API call you need to:

• 1. Have a valid API key
• 2. Use the correct protocol, HTTP and/or HTTPS, depending on your configuration
• 3. Use the correct HTTP verb
• 4. Use a valid API method URL with correctly set parameters
• 5. Send a request body if the API method requires it, format the body correctly and set the format in the "Content-Type" HTTP header of the HTTP request
• define the format of the response using the "Accept" HTTP header of the HTTP request

The implementation is dependant on the programming language and platform you use, so please refer to your programming language documentation for details.

API Key

All API calls require an API Key. These can be created in the WebGUI if your APSIS account has access to the API service. Please visit "API Authentication" for more details on how to create, manage and use API Keys.

HTTP Verb

Depending on the action, an API method performs different HTTP Verbs (sometimes referred to as HTTP Request Methods). These define whether the method should retrieve, remove, create, or update data. It is important to use the correct HTTP Verb in each API call, as an incorrect HTTP Verb could alter the meaning of the API call or result in an error being returned. Which HTTP Verb that should be used for each API call is listed in the documentation for each method. The HTTP Verbs supported by the APSIS API are:

• GET - retrieves data
• POST - update an existing data object or create a new object
• DELETE - removes data

URI and URL Parameters

Each API method has a URI, which is the URL that should be called (with the correct HTTP Verb) to execute the method in question. For some methods, this URI contains URL Parameters (sometimes referred to as Query Parameters). These are required parameters used to define the object the API method will act upon. For example: if you want to update a mailing list you need to set the MailinglistID in the URL itself to define which Mailing List to update. According to the method documentation, the URI for this method is:

http://se.api.anpdm.com/v1/mailinglists/{MailinglistID}

To update the Mailing List with the ID "123" the call would thus be:

http://se.api.anpdm.com/v1/mailinglists/123

Body Parameters

Some API methods require body parameters. These are parameters that are sent in the body of the HTTP request. The body is a text in either XML or JSON format. The choice of format does not impact the functionality of the API itself. Select the format that you feel most comfortable with and the one that your programming platform can handle most efficiently. Define what format to use by setting the "Content-Type" HTTP header. Either set the header to be "application/json" or to "text/xml".

Please note: If the header is not set, the API assumes that the body is formatted in XML. Ensure that the format of the content of the request body matches the content type set in the header, otherwise the API request will fail. Each method that uses body parameters has example body values in both XML and JSON in the method documentation, which makes it easy to see exactly how a valid request body should look like.

The UpdateNewsletter method's body might display like this in JSON format:


And like this in XML format:

Set response format

The response an API method returns can be formatted as either JSON or XML, just as the body parameters in the API request. Use the "Accept" HTTP header in the API request to set which format the response will have. Valid values are either "application/json" or "text/xml".

The GetSubscribersPaginated might return the following if the "Accept" header is set to "text/xml":


And the following if the "Accept" header is set to "application/json":



Please see "How to handle a response" under About queued methods for details of what to do with the API response.