Common API conventions
At a glance
- Summary
- Implicit contract of endpoints exposed by the platform and third-party integrations.
- Objective
- Align integrations on predictable patterns (HTTP codes, JSON envelopes).
- Who this page is for
- Backend developers & integrators.
- Prerequisites
- REST, JSON, HTTP codes.
Versioning
URL prefix or Accept-Version header depending on the endpoint — always indicated in the endpoint sheet.
Errors
Homogeneous JSON envelope: error.code, error.message, optional error.details[].
Endpoint table (example)
| Method | Path | Role |
|---|---|---|
GET | /api/v1/health | Liveness probe |
POST | /api/v1/events | Event ingestion |
GET | /api/v1/exports/:id | Signed download |
Error response
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Required field missing",
"details": [{ "field": "email", "issue": "required" }]
}
}