Appearance
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": "…"
}| Field | Meaning |
|---|---|
success | true for a 2xx answer, false for an error |
message | short text a person can read; empty on most successes |
data | the result: an object, a list, or [] |
total | lists only: the number of rows that match, before paging |
csrf_token | the session's CSRF token, also sent as the X-CSRF-Token header |
metaData | names 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" } }| Status | When |
|---|---|
| 400 / 422 | the request is wrong: missing or invalid fields |
| 401 | not signed in, or the API key is missing or wrong |
| 403 | signed in but not allowed: missing permission, module not enabled, wrong organization |
| 404 | no such route, or no such row in your organization (another organization's row is a 404 too) |
| 409 | a conflict with the current state, for example variant_conflict |
| 413 | the JSON body is too large |
| 429 | rate limited: wait for the Retry-After seconds |
| 500 | something 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=DESCQueryParams::paging()readsstartandlimit;QueryParams::orderBy($allowed, $default)readssortanddir(ASCorDESC) against a list of allowed fields, so a request can never put SQL intoORDER BY.- A few older lists use their own names (the audit log takes
limitandoffset). Each route's comment in its file underappcenter-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.
- Any
GETreturns the token (csrf_tokenin the body,X-CSRF-Tokenheader).GET /meis the usual first call. - Send it back on every
POST,PUT,PATCHandDELETEas the headerX-CSRF-Token(orX-XSRF-Token). - 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.
| What | Limit |
|---|---|
| Sign-in attempts | 10 per 15 minutes per address and per user name |
| Wrong MFA codes | 5 per user and 20 per address per 10 minutes |
| Tenant API: wrong keys | 30 per address per 5 minutes |
| Tenant API: calls | 120 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.