How to use GET requests

Expanding relations, filtering fields, and sorting

The API provides flexible ways to fetch exactly the data that you need.

In every section of the API, you can make GET requests to fetch the list of respective items.
The basic GET request is:
GET /api/v1/entity
for example, GET /api/v1/products will return the list of products.

By default, relational data is hidden in most endpoints to improve performance. For example, products by default will load without variants and images. If you need that data, you can explicitly expand it, using:
GET /api/v1/entity?expand=relation1,relation2
You can find the names of relations that can be expanded on the reference page for each GET endpoint.
Alternatively, you can expand all relations, using:
GET /api/v1/entity?expand=all

If you need to fetch only some fields, you can use:
GET /api/v1/entity?fields=field1,field2
for example, GET /api/v1/products?fields=id,title will return products in such format:

JSON

{
  "id": 298,
  "title": "Hello kitty 1001"
}

You can sort data by almost any field using the sort property in GET, like this:
GET /api/v1/entity?sort=field1,field2
To sort in a descending order, add ! before the field name, so for example, to sort products by descending title and then ascending price, use: GET /api/v1/products?sort=!title,price

Response wrapper and pagination

Data from most GET endpoints (except those that don't require pagination) will come in a wrapper, like this:

JSON

{
  "items": [],
  "_links": {
    "self": "<String>",
    "next": "<String>",
    "prev": "<String>",
    "first": "<String>",
    "last": "<String>",
  },
  "_meta": {
    "totalCount": "<Int>", // total numer of items in set
    "perPage": "<Int>", // page size
    "currentPage": "<Int>", // current page
    "pageCount": "<Int>" // number of pages according to page size
  }
}

Actual data will be inside the items array, and the rest will be metadata that you can use for pagination.
If you wish to load another page, you can either refer to URLs in the _links section, or add ?page to the GET request, like this:
GET /api/v1/products?page=2

Sometimes, on pages like Orders, you need to find which page the order you are looking for is on. For that case, try a request like this:
GET /api/v1/orders/1000/page,
where 1000 is the order ID, and you will get back the page number.

Finally, if you wish to load a lot of items at once, you can explicitly specify the page size:
GET /api/v1/orders?size=200
will make the API load 200 orders per page. Please be aware that this might affect performance.