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 URL's 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 all 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 just by filling in a form on a web page. There you can also see exactly how the request and the response looks. In short, to make an API call you need to:
  • have a valid API key
  • use the correct protocol, HTTP and/or HTTPS, depending on your configuration
  • use the correct HTTP verb
  • use a valid API method URL with correctly set parameters
  • 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
Exactly how to implement these steps depends on what programming language and platform that is used, so please refer to your programming language documentation for details.

API Key

All API calls require and API Key, which can be created in the WebGUI if your Apsis account has access to the API service. Please see "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 if the method should retrieve, remove, create or update data and it is important to use the correct HTTP Verb in each API call. Using 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, i.e. 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), which 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 have to set the MailinglistID in the URL itself to define what 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 sent in the body of the HTTP request. The body is a text in either XML or JSON format, which format to use is completely up to the user of the API and does not impact the functionality of the API itself. Pick the format that you feel most comfortable with and that the programming platform you are using 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".

NB! If the header is not set the API assumes that the body is formatted in XML. Make sure 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.

For example the UpdateNewsletter methods body looks 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". For example, the GetSubscribersPaginated returns 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.