REST Conventions

All MATIH Platform APIs follow a consistent set of REST conventions. These conventions ensure that developers interacting with any service encounter the same URL patterns, HTTP method semantics, query parameter formats, and pagination behavior.

URL Structure

All API URLs follow this pattern:

/api/v1/:resource[/:id][/:sub-resource]

Component	Description	Example
`/api`	API namespace prefix	Always present
`/v1`	API version	Major version only
`/:resource`	Plural resource name	`/dashboards`, `/users`, `/tenants`
`/:id`	Resource identifier	`/dashboards/dash-123`
`/:sub-resource`	Nested resource	`/dashboards/dash-123/widgets`

HTTP Methods

Method	Semantics	Idempotent	Response Code
GET	Retrieve resource(s)	Yes	200 OK
POST	Create a new resource	No	201 Created
PUT	Full replacement of a resource	Yes	200 OK
PATCH	Partial update of a resource	No	200 OK
DELETE	Remove a resource	Yes	204 No Content

Query Parameters

Filtering

Filters use field-based query parameters:

GET /api/v1/dashboards?status=published&created_by=user-123

Sorting

Sort by field name with optional direction:

GET /api/v1/dashboards?sort=created_at&direction=desc

Parameter	Values	Default
`sort`	Any sortable field name	`created_at`
`direction`	`asc`, `desc`	`desc`

Pagination

All list endpoints support cursor-based or offset-based pagination:

GET /api/v1/dashboards?page=0&size=20

Parameter	Description	Default	Maximum
`page`	Zero-based page number	0	--
`size`	Items per page	20	100

Paginated Response

{
  "success": true,
  "data": [ ],
  "metadata": {
    "timestamp": "2026-02-12T10:30:00Z",
    "requestId": "abc-123",
    "version": "v1"
  },
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 142,
    "totalPages": 8,
    "hasNext": true
  }
}

Request Headers

Header	Required	Description
`Authorization`	Yes (except public endpoints)	`Bearer <access_token>`
`Content-Type`	Yes (for POST/PUT/PATCH)	`application/json`
`Accept`	No	`application/json` (default)
`X-Correlation-ID`	No	Client-provided correlation ID for tracing
`X-Request-ID`	No (set by gateway)	Unique request identifier

Response Headers

Header	Description
`X-Request-ID`	Unique identifier for this request
`X-Correlation-ID`	Correlation ID (echoed from request or generated)
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Naming Conventions

Convention	Example
Resource names are plural	`/dashboards`, `/users`, `/tenants`
URL path segments use kebab-case	`/api-keys`, `/data-sources`
Query parameters use snake_case	`created_by`, `sort_order`
JSON fields use camelCase	`tenantId`, `createdAt`, `dashboardName`

Versioning Strategy

API versioning uses URL-path versioning with major versions only:

Version	URL	Notes
v1	`/api/v1/resource`	Current stable version
v2	`/api/v2/resource`	Future version (when breaking changes are needed)

Minor and patch-level changes (adding optional fields, new endpoints) are made within the current version. Breaking changes (removing fields, changing semantics) require a new major version.

Error Handling -- Error response conventions
Authentication -- API authentication patterns
Rate Limiting -- Rate limiting conventions

Overview Error Handling