Method Types
Queued
Some API calls are more resource intensive than others. In order to keep the API quick and responsive, the calls that take up more resources and time to execute are placed in a queue to be executed under more controlled circumstances. These methods are marked as “Queued” in the API documentation.There are several reasons why using queued methods is a great idea. One of them is that it reduces the risk of timeouts when performing massive operations, such as deleting a large quantity of subscribers at once or exporting large amounts of data. Queued methods mean that a queued call can be run more efficiently and thereby improve the overall response time, especially for the non-queued calls.
An example of a queued method is GetAllSubscribers, which returns all subscribers for an account (potentially hundreds of thousands of entries). GetSubscribersPaginated is a non-queued method that only returns a subset of 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 quantity of data needs to be retrieved from APSIS Pro.
When you place a call to a queued method, you will receive a PollURL as a part of the “Result” in the response. 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. Once a PollURL has been retrieved, this URL needs to be polled (i.e. called multiple consecutive times) until the queued operation is completed.
Best practice is to call the PollURL with longer and longer pauses between each call and to set a limit to the number of calls made. Otherwise, your application might keep polling – even if something would go wrong.
Once the State is set to completed, you need to fetch the data by making a GET request to the DataUrl that was returned from the polling call. This is the URL that contains the actual result and the return data from the API call. In the result, you will also find information regarding subscribers that might have failed to be imported.
Once the operation is completed, poll the DataUrl to retrieve the originally requested data. Please note that the DataUrl in the poll response will be empty until the operation is completed and the state is set to completed. The file returned from the DataUrl might be very large, depending on the preferences of the operation.
Paginated
These methods are suitable to use when you prefer to work with a subset of data rather than all data. The concept is comparable to reading selected pages in a book, rather than consuming the book as a whole.Paginated methods return paginated results according to the input parameters PageNumber and PageSize. This is particularly useful for large result sets, when you want to limit the amount of data transferred with each API-call.
PageNumber and PageSize
PageNumber: The page in the resultset to return starts with 1. PageSize is the size of each page resultset. For instance, a call with PageNumber 1 and PageSize 5 will return the first five elements. To fetch the next five, make a call with PageNumber 2 and PageSize 5. The last page of the result may contain fewer elements than specified by PageSize. For instance, if there are only 8 items available in total, the call using PageNumber 2 and PageSize 5 will return the last three elements. If trying to fetch page 3 of that result set, an error message will be returned, similar to: “The page 3 specified is greater than the number of pages available (2)”.TotalCounts and TotalPages
To help determining how many items there are in total and how many pages that are required to get the full result, the paginated methods return the values TotalCount and TotalPages. TotalCounts is the total amount of items in the list.TotalPages is the number of pages required to get the complete result, according the the specified page size. This will be useful when constructing a loop to fetch all results, or when displaying a paged result set in a user interface.
For instance: Let us assume that we have a list that contains 22 items. If we fetch a paged results, specifying PageSize: 10 will return TotalCount: 22 and TotalPages: 3.