Skip to main content

App API

In this page you will learn how the App API works as a whole. Each operation is described in the API reference.

One surface, read-only​

The App API lives under /api/app/v1 on the API host of the platform your app is installed on. It is the only API an installation token can call: every other route answers 403 with the problem forbidden-for-apps, whatever the scopes. Version 1 has no write operation.

ResourceOperationsScope
InstallationGET /installationnone
OrganizationsGET /organizations, GET /organizations/{id}read_organizations
ProductsGET /products, GET /products/{id}, GET /products/{id}/scoresread_products
IngredientsGET /ingredients, GET /ingredients/{id}, GET /ingredients/{id}/scoresread_ingredients
PackagingsGET /packagings, GET /packagings/{id}, GET /packagings/{id}/scoresread_packagings
QuestionnairesGET /questionnaires?entityType=&entityId=, GET /questionnaires/{id}read_questionnaires and the entity's read scope
BillingGET /billing/plans, subscriptions and chargesnone, see Billing

Authenticate​

Send the installation token of your OAuth install in every request:

GET /api/app/v1/products/345 HTTP/1.1
Host: {tenant}-api.example.com
Authorization: Bearer <access_token>

The token lasts an hour. Refresh it before it expires, or after a 401. The format of every answer is JSON: there is no other.

Organizations​

An installation covers the organizations an administrator granted and their descendants. Everything the API returns is limited to them:

  • a collection lists only entities of covered organizations;
  • an item outside them answers 404, the same answer as an item that does not exist;
  • a filter (organizationId, entityId) that names something outside them answers 404.

GET /installation tells you what you were granted.

Pagination​

Collections answer a page and a cursor:

{
"items": [{ "id": 345, "organizationId": 12, "name": "Granola", "...": "..." }],
"nextCursor": "eyJsYXN0SWQiOjM0NX0.9fGQ"
}
ParameterMeaning
limitThe page size, 50 by default and 100 at most
afterThe nextCursor of the previous page
updatedSinceOnly entities updated at or after this date (RFC 3339), on the collections that have one

Items come in ascending id order. When nextCursor is null, you have read everything. A cursor is opaque and signed: pass it back unchanged, with the same filters, to the same resource, from the same installation. Anything else answers 400 with the problem invalid-cursor: start again without after. A cursor never widens what you can read: the organizations and the filters are applied again on every request.

To keep a copy up to date, read once from the start, then read again with updatedSince set to the time you began the previous read.

Errors​

Errors are RFC 7807 problems, application/problem+json, and each type is the address of the error's page: see Errors. Match on type, not on the text:

{
"type": "https://dev.positive-app.fr/errors/scope-missing",
"title": "Scope missing",
"status": 403,
"detail": "The installation was not granted the scope \"read_products\"."
}
Statustype ends withMeaning
400invalid-cursorThe cursor is not valid for this installation, resource and filters
400invalid-parameterA parameter is malformed
401The token is missing, expired, or the installation was uninstalled or suspended
403scope-missingThe scope was not granted
403forbidden-for-appsThe route is not part of the App API
404not-foundNot found, or outside the covered organizations
429rate-limitedToo many requests: wait Retry-After seconds

Rate limit​

An installation may make 600 requests per minute across the whole App API (the billing operations also have their own, stricter limit). Every answer carries:

HeaderMeaning
X-RateLimit-LimitThe budget: 600
X-RateLimit-RemainingWhat is left in the window
X-RateLimit-ResetThe Unix time when the budget is whole again

A request over the budget answers 429 with Retry-After, in seconds. Prefer webhooks to polling.

Formats​

Dates and times are RFC 3339 strings. Identifiers are integers, except the installation (a UUID) and the billing objects (strings). A field that may be absent is null, never missing. New fields can be added to any object in version 1: ignore the ones you do not know.