Skip to content
ReferenceForDeveloper

API conventions ​

These rules hold for BMA's own API, every module's routes and the Tenant API. The marketplace's host API has its own contract and OpenAPI file.

Addresses ​

The API lives under /api/index.php/… (the front controller also accepts /api/v1/… and /api/…, and strips whichever prefix it finds). Paths in these guides start after that prefix: GET /me means GET /api/index.php/me.

The envelope ​

Every answer is JSON with the same shape. It is written by ApiResponse (appcenter-next/api/lib/Response.php).

json
{
  "success": true,
  "message": "",
  "data": { "id": 42, "name": "Northwind Motors" },
  "metaData": { "root": "data", "totalProperty": "total", "successProperty": "success", "messageProperty": "message" },
  "total": 118,
  "csrf_token": "…"
}
FieldMeaning
successtrue for a 2xx answer, false for an error
messageshort text a person can read; empty on most successes
datathe result: an object, a list, or []
totallists only: the number of rows that match, before paging
csrf_tokenthe session's CSRF token, also sent as the X-CSRF-Token header
metaDatanames the fields above, for grid components; ignore it

In PHP, answer with ApiResponse::ok($data, $message = '', $total = null) or ApiResponse::error($message, $status = 400, $data = null). Both end the request.

Errors ​

An error has success: false, an HTTP status, a message, and usually a machine-readable code in data.code:

json
{ "success": false, "message": "Module not enabled", "data": { "code": "module_not_enabled", "module": "sawscore" } }
StatusWhen
400 / 422the request is wrong: missing or invalid fields
401not signed in, or the API key is missing or wrong
403signed in but not allowed: missing permission, module not enabled, wrong organization
404no such route, or no such row in your organization (another organization's row is a 404 too)
409a conflict with the current state, for example variant_conflict
413the JSON body is too large
429rate limited: wait for the Retry-After seconds
500something broke on the server

Unexpected errors are answered by ApiResponse::fail($publicMessage, $status, $e, $errorCode). The client gets the public message and data: {error, code, request_id}, and the response has an X-Request-Id header; the exception's own text goes only to the server log, under that request id. Give the request id to BMA staff when you report a problem. An exception of class UserFacingException is the one exception whose message is shown as it is.

Lists, paging and sorting ​

Lists that page take start (from 0) and limit (1 to 200, 50 when left out), and return the full count in total:

http
GET /api/index.php/admin/audit?limit=50&offset=100
GET /api/index.php/<module path>?start=0&limit=50&sort=name&dir=DESC
  • QueryParams::paging() reads start and limit; QueryParams::orderBy($allowed, $default) reads sort and dir (ASC or DESC) against a list of allowed fields, so a request can never put SQL into ORDER BY.
  • A few older lists use their own names (the audit log takes limit and offset). Each route's comment in its file under appcenter-next/api/routes/ says what it takes.
  • There is no cursor paging.

CSRF ​

Browser sessions use a cookie, so every change needs the session's CSRF token.

  1. Any GET returns the token (csrf_token in the body, X-CSRF-Token header). GET /me is the usual first call.
  2. Send it back on every POST, PUT, PATCH and DELETE as the header X-CSRF-Token (or X-XSRF-Token).
  3. A missing or wrong token gets 403 Invalid or missing CSRF token.

BMA's shell and a module's host().api client do this for you. Exempt are the sign-in steps before a session exists, the Tenant API (it uses an API key, not a cookie), and the paths a module lists in api.public_paths (those must check their own signature, as a webhook does).

Rate limits ​

Limits answer 429 with data.code: "rate_limited", data.retry_after and a Retry-After header.

WhatLimit
Sign-in attempts10 per 15 minutes per address and per user name
Wrong MFA codes5 per user and 20 per address per 10 minutes
Tenant API: wrong keys30 per address per 5 minutes
Tenant API: calls120 per minute per key, 600 per minute per organization

Cached answers ​

A GET that sends If-None-Match with the ETag of an earlier answer gets 304 with no body when nothing changed. The tag covers the whole body, including the session's CSRF token, so it never matches another session's copy. Answers are always Cache-Control: no-store.