Links and Pagination
How to navigate the API responses.
Links
Amplemarket provides a RESTful API including the concept of hyperlinking in order to facilitate user’s navigating the API without necessarily having to build URLs.
For this responses MAY include _links
member in order to facilitate navigation, inspired by the HAL media type.
The _links
member is an object whose members correspond to a name that represents the link relationship.
All links are relative, and thus require appending on top of a Base URL that should be configurable.
E.g. a GET
request could be performed on a “self” link:
GET {{base_url}}{{response._links.self.href}}
Link Object
A link object is composed of the following fields:
href
(string) - A relative URL that represents a hyperlink to another related object
Example:
Pagination
Certain endpoints that return large number of results will require pagination in order to transverse and visualize all the data.
The approach that was adopted is Cursor-based pagination (aka keyset pagination) with the following query parameters: page[size]
, page[before]
, and page[after]
As the cursor may change based on the results being returned (e.g. for Email Validation it’s based on the email, while for Lead Lists it’s based on the ID of the lead list’s entry) it’s highly recommended to follow the links next
or prev
within the response (e.g. response._links.next.href
).
Notes:
-
The
next
andprevious
links will only appear when there are items available. -
The results that will appear will be exclusive of the values provided in the
page[before]
andpage[after]
query parameters.
Example:
Searcher pagination
Certain special endpoints such as Search people take a different pagination approach, where the the pagination is done through the POST request’s body using the page
and page_size
fields.
For these cases the response will include a _pagination
object:
page
(integer) - The current page numberpage_size
(integer) - The number of entries per pagetotal_pages
(integer) - The total number of pages in the search resultstotal
(integer) - The total number of entries in the search results
Example:
Was this page helpful?