The HTTP Request

URI

The request URI identifies the resource you want to handle. The first part of the URI is the scope: Partners, Shops, Drop Points, or Me. The remainder is the path to a resource. Putting a scope and path together as /<scope>/<path> looks like, for example, /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 you fetch a list of resources. The filters available for a given endpoint are specified in its 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 combined like this: ?filter[deleted_at]=&filter[name]=RE-Z*. This returns records that are not deleted (the deleted_at timestamp is null) and whose 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