About queued methods

Introduction

Some API calls are quite resource intensive and to reduce the load on the system these calls are placed in a queue. The purpose of this is to be able to process the calls in a more controlled manner. These methods are all marked as "Queued" in the API documentation. There are several reasons for using queued methods:

  • Reduces the risk of timeouts for very big operations, for example when deleting tens thousands of Subscribers
  • Reduce the overall response time of the API since heavy tasks kan be scheduled more efficiently
  • Give the API users the ability to export all data from the API in a very controlled manner

When to use queued methods

Almost every queued method has an alternative that returns a subset of the data immediately. An example is GetAllSubscribers that is a queued method that returns all subscribers for an account (potentially thousands) and GetSubscribersPaginated is a method that returns a subset of all subscribers. It is recommended to use the non-queued methods whenever the API needs to give an immediate response and the queued methods whenever a large amount of data needs to be retrieved from APSIS Pro.

Initial method call

There are three steps to making a queued method call. First make a request to the method's URL, for example DELETE http://se.api.anpdm.com/v1/mailinglists/ for DeleteMultipleMailingLists. This call will return the following:


Note that the above data format and the file extension for the DataUrl depend on the HTTP "Accept" header value used and can be "xml" or "json".
OperationGuid is a unique ID for this operation, and it is a good idea to log this ID in case of an error. If there is an issue with the API call APSIS support can use the OperationGuid to investigate what was the issue. PollURL is a URL to a file that reports the status of the operation. This URL is used in the next step of the queued method processing.

Polling

Once a PollURL has been retrieved, this URL needs to be polled (i.e. called multiple consecutive times) until the queued operation is completed. NB! We strongly recommend you to make calls to the PollURL further and further apart as well as setting a limit to the maximum number of calls, this to avoid making unnecessary calls to the API server as well as avoiding processes that will never end.

There are no guarantees for how long the processing of a queued method might take, so it is recommended to use queued methods with the assumption that the polling might take minutes or possibly also an hour or two (even if it most likely will take merely seconds). If it takes longer than a couple of hours something has probably gone wrong and APSIS' support should be contacted (please be prepared to inform APSIS support about the OperationGuid). Calling the PollURL will return an answer such as this:


Note that the above data format and the file extension for the DataUrl depend on the HTTP "Accept" header value used and can be "xml" or "json".
The State is the current state of the queued operation and once it is "2" for "Completed" the operation has finished and the actual data of the operation can be retrieved using the DataUrl. There are several possible States and they are all listed below.

State StateName Description
0 Waiting The processing of the operation has not been started yet.
1 Started The operation is currently being processed.
2 Completed The operation has finished. Retreive the result of the operation using the DataUrl.
-1 Error There was an issue with the operation. See the "Message" for further details.
-2 FatalError There was a major issue with the operation. See the "Message" for further details . If needed, contact the Apsis support identifying the operation with the OperationGuid.
-3 Rejected_ToOld The queued job was rejected because it was in the queue too long.


The PollURL and the data result will be available for several days, after which they will be deleted from the server. It is recommended to download the requested data as soon as possible.

Retrieve Data

Once the operation is completed, poll the DataUrl to retrieve the originally requested data (note that before the operation is completed the DataUrl in the poll response will be empty). This might be the status of deleting multiple subscribers or retrieving all mailing lists on an account with many lists. Note that this file might be very large, depending on the details of the operation. Exactly what data each queued method returns via the DataUrl is visible in the documentation for each method.

How to handle an API response

Once a request has been sent to the APSIS API, next step is to handle the response from the API call. All responses contain the same basic structure.

The Response

All responses contain a "code" and a "message" with a status of how the request went and a "result" with the actual content of the response. An example response from the GetMailingListDetails can look like this:


Note that the above data format depends on the HTTP "Accept" header value used and can be "xml" or "json".

Response format

The response can be formatted as either JSON or XML, depending on what has been defined in the request using the "Accept" HTTP header. See "How to make an API request" for details. The "Content-Type" HTTP header in the API response is set to either "application/json" or "text/xml".

Result

The result contains the actual content of the API response, It might be an ID of a newly created newsletter or information about subscribers. See the documentation of each individual API method for details about what data the result part of the response contains. If there was an issue with the request (i.e. another status code than "1" is returned) the result will be empty.

Handle the response

To handle a response follow these steps:

  • If unsure of the format of the content, check the "Content-Type" HTTP header in the response so you know if you need to parse JSON or XML.
  • Check either the HTTP Status Code in the response or the "code" in the response body to see if all went OK or if there was an error.
  • If all is OK then read the content of the results node and handle the returned data as you wish. If it is a Queued method please refer to "How to handle Queued methods" for details on how to handle the response.
  • If there is an error, make sure you can handle all the types of errors and also log what has happened.
  • If required, contact APSIS support to resolve any issue, and if you do so please supply as much information about the request and response as possible. Especially take note of the OperationGUID returned by the server, this is a unique ID for the request that can be used to help APSIS' support to diagnose the error.


Exactly how to implement these steps depends on what programming language and platform is used, so please refer to your programming language documentation for details.