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 instance when deleting a significant number of Subscribers
• Reduces the overall response time of the API, as heavy tasks kan be scheduled more efficiently
• Gives 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, which is a queued method that returns all subscribers in an account (potentially thousands). Another example is GetSubscribersPaginated, which 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.

Step 1: Initial Method Call

There are three steps that you need to take to make a queued method call. The first one is to make a request to the method's URL, for example DELETE http://se.apidoc.anpasia.com/v1/mailinglists/ for DeleteMultipleMailingLists. This call will return the following:


Note that the above data format and the file extension for the DataUrl depends 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 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.

Step 2: 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. Please note: to avoid making unnecessary calls and processes that never end, we strongly recommend that you make calls to the PollURL, distribute them further and further away in time, and set a limit to the maximum number of calls.

The processing of a queued method normally takes a few seconds. However, as there are no guarantees, it is recommended to assume that it might take a few minutes, and in rare instances: an hour or two. If the processing exceeds two hours, please contact APSIS support and inform them 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 depends on the HTTP "Accept" header value used and can be "xml" or "json".

The "State" is the current state of the queued operation. Once the state is "2" or "complete", the operation is finalised and the data 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. Retrieve the result of the operation using the DataUrl.
-1	Error	There was an issue with the operation. View the "Message" for further details.
-2	FatalError	There was a major issue with the operation. View the "Message" for further details. If needed, contact the APSIS support to identify the operation with the OperationGuid.
-3	Rejected_ToOld	The queued job was rejected because it was in the queue for too long.

The PollURL and the data result will be available for several days, before being deleted from the server. It is recommended that you download the requested data as soon as possible.

Step 3: Retrieve Data

Once the operation is completed, poll the DataUrl to retrieve the originally requested data. Note: the DataUrl in the poll response will be empty until the operation is completed.

The requested data might be the status of deleting multiple subscribers or retrieving all mailing lists on an account with many lists. Depending on the details of the operation, this file might be quite large. Exactly what data each queued method returns via the DataUrl is visible in the documentation for each method.

How to Handle an API Response

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

Step 1: The Response

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


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

Step 2: 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. View the "How to make an API request" section of this guide for details. The "Content-Type" HTTP header in the API response is set to either "application/json" or "text/xml".

Step 3: Result

The result contains the actual content of the API response. This could be the ID of a newly created newsletter or information about subscribers. View the documentation of each individual API method to get 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

Follow these steps to handle the response:

• If you are unsure of the format of the content, check the "Content-Type" HTTP header in the response to know if you need to parse JSON or XML.
• Check the HTTP Status Code in the response or the "code" in the response body to ensure that there were not any errors.
• If everything checks out, read the content of the results node and handle the returned data as you wish. If it is a Queued method, please read "How to handle Queued methods".
• If there is an error, make sure you can handle all types of errors and log what has happened.
• Contact APSIS' support if you need help with handling and resolving issues. Please submit as much information about the request and response as possible. Take note of the OperationGuid returned by the server, as this is a unique ID for the request and a pivotal part when APSIS' support diagnoses the error.

Please note that the implementation of these steps depend on programming language and platform. Refer to your programming language documentation for details.