API Conventions

The Vanilo REST API returns responses in a consistent manner, based on several conventions. These standards are described below.

The API definitions are based on and documented with the OpenAPI 3 Standard.

The Vanilo OpenAPI reference is available at: Vanilo Cloud API Reference.

Identifiers

Returned objects have identifiers returned as the id property. The format of these identifiers is varying, it can be:

  • numeric, examples: 3211, 1564578985;
  • textual, examples: PCD-7321, 602-1FKD-1ET1, color or 5f21ed4e1b;
  • UUID: 0c94aace-04ac-4da5-a57d-72f13f589406;

It is important that you treat all these identifiers as strings in your applications. Even though if you get an id that looks numeric, there's no guarantee that new entries will also have a numeric id.

Therefore, your application must treat every id coming from Vanilo as a string.

Date & Time Formats

Date and DateTime values are returned as strings formatted as defined by RFC 3339, section 5.6, for example:

  • date: 2019-07-21
  • date-time 2021-04-24T19:17:06.000000Z

All dates and times are in the UTC Timezone.

Collections

If a response returns a collection of items (eg. a list of products, a list of orders, etc) then the response is always being wrapped in the following "envelope":

{
  "data": [],
  "links": {
    "first": "https://your.shop/api/1.0/resource?page=1",
    "last": "https://your.shop/api/1.0/resource?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://your.shop/api/1.0/resource",
    "per_page": 100,
    "to": 2,
    "total": 2
  }
}

Items (Data)

The data property is an array that contains multiple objects of the same type (eg. products, orders, etc).

Filtering

Collections can be filtered by multiple criteria. The swagger spec of each resource contains their particular filters, but all of them follow the same convention, that's described below.

Filters are passed as query parameters: /api/1.0/orders?filter[user_id]=444.

Multiple filters can be passed: /api/1.0/orders?filter[status]=cancelled&filter[user_id]=888.

Multiple values can be passed, using colons as separator: /api/1.0/orders?filter[user_id]=444,888

To filter by data in deeper level, use the "dot notation": /api/1.0/orders?filter[billing_address.email][email protected]

The filters check for exact values by default. To get the items matching greater than/less than/not equals conditions you can use the colon notations like ?filter[created_at:gt]=2023-11-27:00:00:00.

The Table of Comparison Operators

Comparison Notation Example Meaning
> gt /api/1.0/orders?filter[id:gt]=37556 Orders with id greater than 37556
>= gte /api/1.0/orders?filter[id:gte]=41222 Orders with id greater than or equal to 41222
< lt /api/1.0/orders?filter[id:lt]=3550 Orders with id less than 3550
<= lte /api/1.0/orders?filter[id:lte]=1730 Orders with id less than or equal to 1730
!= neq /api/1.0/orders?filter[status:neq]=cancelled Orders with non-cancelled status

Further Examples:

  • Orders created between May 1 and May 8: /api/1.0/orders?filter[created_at:gte]=2023-05-01T00:00:00&filter[created_at:lte]=2023-05-08T23:59:59
  • Orders modified since a specific date: /api/1.0/orders?filter[updated_at:gt]=2023-09:07:15:30:00
  • Orders with non-cancelled and non-completed status: /api/1.0/orders?filter[status:neq]=cancelled,completed

Sorting

Sorting of the items happens via the query sort query parameter: /api/1.0/users?sort=name. This sorts the results in ascending order (A-Z).

To sort in descending order (Z-A) add a hyphen to the field: /api/1.0/users?sort=-name.

To sort by multiple columns, separate the column names by a colon: /api/1.0/users?sort=lastname,firstname

Including Sub-resources

Certain resources, like order, contain several sub-resources (eg. payments, shipments, adjustments) which are not included in the response by default. To include them with the response, use the includes query parameter.

Examples:

  • To include the payments with the orders: /api/1.0/orders?include=payments
  • To include the payments and the shipments with the orders: /api/1.0/orders?include=payments,shipments

The links property takes the guesswork out of dealing with pagination: it gives you the relative links to the current page. Likely the most important entry for an API is the next element which gives you the link to the next page of items as long as there are more results. If there are no more results, it returns null.

Meta

The meta property gives information about the collection and the current page:

  • current_page eg. 2 - which page are you currently at
  • from eg. 101 - the offset of the first element on the current page
  • last_page eg. 3 - the number of the last page (ie. total number of pages)
  • path eg. https://your.shop/api/1.0/resource - the link to the collection resource
  • per_page eg. 100 - the number of items per page
  • to eg. 199 - the offset of the last element on the current page
  • total eg. 281 - the number of total items in the current collection

Creating Resources

Creating resources can be done via POST requests to the collection, eg.: https://your.shop/api/1.0/products.

Whenever you create a resource, the response will have the following structure:

  • HTTP 201 status
  • Location header will contain the URL of the newly created resource
  • The payload is JSON that minimally contains a message property that describes the resource(s) created.

Example:

HTTP/1.1 201 Created
Date: Mon, 26 Apr 2021 12:22:40 GMT
Location: https://your.shop/api/1.0/products/KNCB-1131
Content-Type: application/json

{
  "message": "The product has been created"
}

Updating Resources

Resources can be updated using the PATCH method on an existing resource like https://your.shop/api/1.0/products/KNCB-1131

This allows partial update, meaning you only need to supply the fields in the payload that you want to update.

PUT methods for idempotent updates are also planned in later versions of the API

Successful responses after an update have the following traits:

  • HTTP 200 status
  • The payload is JSON that minimally contains a message property informing that the resource has been updated.

Example:

HTTP/1.1 200 OK
Date: Mon, 26 Apr 2021 19:18:40 GMT
Content-Type: application/json

{
  "message": "The product has been updated"
}

Deleting Resources

Use the DELETE method on an existing resource like https://your.shop/api/1.0/products/KNCB-1131 to remove it.

Possible responses are:

  • 404 Not Found - if the resource was not found on the URL,
  • 409 Conflict - if the resource can't be deleted because it's still needed.

After a successful deletion, you'll get a 204 No Content response without any payload. This means that getting a 204 is the confirmation of the deletion of the resource.

Example:

HTTP/1.1 204 No Content
Date: Mon,26 Apr 2021 17:26:44 GMT 
Cache-control: no-cache,private