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}}

A link object is composed of the following fields:

  • href (string) - A relative URL that represents a hyperlink to another related object

Example:

{
  "_links": {
    "self": { "href": "/email-validations/1" }
  }
}

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 and previous 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] and page[after] query parameters.

Example:

  "_links": {
    "self": { "href": "/lead-lists/81f63c2e-edbd-4c1a-9168-542ede3ce98f" },
    "prev": { "href": "/lead-lists/1?page[size]=100&page[before]=81f63c2e-edbd-4c1a-9168-542ede3ce98a" },
    "next": { "href": "/lead-lists/1?page[size]=100&page[after]=81f63c2e-edbd-4c1a-9168-542ede3ce98a" }
  }

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 number
  • page_size (integer) - The number of entries per page
  • total_pages (integer) - The total number of pages in the search results
  • total (integer) - The total number of entries in the search results

Example:

  "_pagination": {
    "page": 1,
    "page_size": 30,
    "total_pages": 100,
    "total": 3000
  }