REST API

A key #

Make one under the project's settings, in API keys. It is shown once and stored as a hash. The key says which project; every request names the data source with ?source=, and one that names none is refused with the names the project has. A project's id never appears in an address.

A key is read and write, or read only (GET, HEAD, OPTIONS), and may be narrowed to some tables of the source it was made on. It acts for the person who made it: taken out of the project, they take its access with them. Writes made with a key are listed in the project's Activity.

curl -H "Authorization: Bearer 10lines_XXXX" \
  "https://10lines.io/api/v1/tables/orders?source=shop&per_page=50&order_by=-total&status[eq]=paid"

What there is #

Listing rows #

A page answers data and, under meta, page, per_page, total and total_pages. A read has five seconds; when counting the rows takes longer, the page still comes back, total_exact is false and total is what is certain.

A big table #

Paging by number makes the database count past every row it skips. A cursor costs the same wherever it lands: start with an empty ?cursor= and a single order_by column, and follow next_cursor until it is null. It does not count the table, so there is no total.

GET /api/v1/tables/orders?source=shop&order_by=id&cursor=
→ {"data": [...], "meta": {"per_page": 25, "next_cursor": "g2gCYQFhAg"}}

GET /api/v1/tables/orders?source=shop&order_by=id&cursor=g2gCYQFhAg
→ {"data": [...], "meta": {"per_page": 25, "next_cursor": null}}

Writing #

A row's values go under data. They are cast and checked against the column's type and its field settings before anything is written, and a refusal is a 422 with an errors map by column.

curl -X POST -H "Authorization: Bearer 10lines_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"data": {"code": "A-1001", "total": 42}}' \
  "https://10lines.io/api/v1/tables/orders?source=shop"

A bulk call carries data as a list (each with an id for an update) or ids for a delete, up to 1000 rows. It is all or nothing, and a refusal names the position or id of every row that failed.

curl -X POST -H "Authorization: Bearer 10lines_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"code": "A-1"}, {"code": "A-2"}]}' \
  "https://10lines.io/api/v1/tables/orders/bulk?source=shop"

curl -X DELETE -H "Authorization: Bearer 10lines_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 2]}' \
  "https://10lines.io/api/v1/tables/orders/bulk?source=shop"

Caching and browsers #

Reads carry an ETag; send it back as If-None-Match and an unchanged answer is a 304 with no body. CORS headers are sent, from any origin unless the server is told otherwise: requests authenticate with a key in a header, not a cookie.

Limits and errors #