The HTTP Request

URI

The request URI identifies the resource we want to handle. The first part of the URI defines the scope for which there is an API; Partner, Shop, Drop Point and Me. The remainder of the URI is the path to some resource. Applying a specific scope and path to /<scope>/<path> could fx. look like /me/vouchers.

Pagination & Sorting

Pagination is implemented using the Keyset pagination strategy, which means that a page can be defined using URL query parameters:

sort_by: The data-column to sort by (default: id).
sort_dir: The direction to sort [asc, desc] (default: asc)
page_from: The point in the data-set to start from
page_size: The number of rows to include in the page (default: 25, maximum: 1000)

Example: Requesting GET /vouchers is the same as requesting GET /vouchers?sort_by=id&sort_dir=asc&page_size=25.

Please note! The value in page_from and the data-field specified in sort_by must be of the same data type.

Filtering & Search

You can use filters to limit a result set whenever getting a list of resources is fetched. Available filters for some particular endpoint are specified in the documentation.

Filters work by using the filter query parameter in the request URL and are controlled by specifying a data-field, an operator and a value - filter[<data-field>]=<operator><value>.

Operator	Meaning	Example
(none)	Is NULL	`?filter[name]=` (no value)
`!`	Is not NULL	`?filter[name]=!` (no value)
(none)	Equal to	`?filter[name]=RE-ZIP`
`!`	Not equal to	`?filter[name]=!RE-ZIP`
`>`	Greater than	`?filter[created_at]=>2023-12-01`
`<`	Less than	`?filter[created_at]=<2023-12-01`
`>=`	Greater than or equal to	`?filter[created_at]=>=2023-12-01`
`<=`	Less than or equal to	`?filter[created_at]=<=2023-12-01`
`><`	Between, inclusive in both ends	`?filter[created_at]=><2023-12-01,2023-12-31`
`*`	Wildcard	`?filter[name]=RE-Z` / `?filter[name]=RE-Z` / `?filter[name]=RE-Z`

Multiple filters can be specified like this: ?filter[deleted_at]=&filter[name]=RE-Z*. This will get records that is not deleted (deleted_at timestamp is null) and where the name begins with “RE-Z”.

Method

Request methods defines the action we wish to perform on a resource. The RE-ZIP API recognizes five HTTP request methods:

Method	Description
GET	Get a resource or list of resources
POST	Create a resource
PUT	Replace a resource
PATCH	Update a resource
DELETE	Delete a resource
QUERY	Same as get but for complex requests where a body is required

Please note! Not all methods are valid for all URIs.

Headers

Header	Description
Host	The domain name of the server
Authorization	HTTP Basic or Bearer authentication
Accept-Version	The desired version of the API
Accept	Content-Types that are acceptable - currently only application/json is available for non-static resources
Accept-Language	Language for system messages - currently only en_UK is supported
Content-Type	The mime type of the body of the request (used with POST, PUT and PATCH requests)
Content-Length	Length (in bytes) of the response message body (used with POST, PUT and PATCH requests)
X-Request-UUID	Optional Request UUID (v4) to identify request/response flows

Body

Data in the request body is only considered if request method is POST or PATCH. Here are some examples:

To update a resource:

PATCH /resource/<Identifier> HTTP/1.1
Host: api.re-zip.com
Authorization: Bearer M5e6aiWrMzMMivbb9WJlYEuWSmW/nQRn/TfcBjwFyhlexcKK2u1QFQfWX8YS4OU5
Accept-Version: 2.0
Accept: application/json
key1=value1&key2=value2

To get a resource:

GET /resource/<Identifier> HTTP/1.1
Host: api.re-zip.com
Authorization: Bearer M5e6aiWrMzMMivbb9WJlYEuWSmW/nQRn/TfcBjwFyhlexcKK2u1QFQfWX8YS4OU5
Accept-Version: 2.0
Accept: application/json