Reading records

Open in the interactive reference

A resource has up to three endpoints for reading, each for a different job:

• GET the collection to list records. Its records are often lighter than the full record. It is the only one that takes filters, sorting, field selection and paging in the query string; see Pagination and querying.
• GET a record by id for one full record.
• POST to search for many full records, with the filters in the request body. A search usually returns the same fields as GET by id; its endpoint shows exactly what it returns.

Not every resource has all three, and their filters differ: some text filters, such as a customer's name, exist only on search, and some structured filters only on the collection. Check the resource's endpoints for the filter you need.

A collection returns its records as the data array, with pagination beside it. A search returns them in data.items.

Only a collection refuses query parameters it does not declare. GET by id and search ignore them, so fields= on GET by id still returns the whole record.

You cannot ask an endpoint to include related records. A field such as customerId holds an id, and reading that customer is a second request, unless the record already embeds the details you need.

A collection query that matches nothing returns 200 with an empty data array, not 404.

Examples

Three ways to read

GET  /accounting/customers
GET  /accounting/customers/{id}
POST /accounting/customers/search