API Design

The MATIH Platform exposes a consistent, well-structured API surface across all 24 microservices. Every API follows shared conventions for URL structure, request/response formats, authentication, error handling, and rate limiting. These conventions are enforced through the commons-java and commons-python shared libraries.

API Surface Overview

All APIs are routed through the Kong API Gateway (port 8080), which handles authentication, rate limiting, and request routing before traffic reaches backend services.

API Sections

Common Patterns

Response Envelope

All APIs return responses in a consistent envelope format:

{
  "success": true,
  "data": { },
  "metadata": {
    "timestamp": "2026-02-12T10:30:00Z",
    "requestId": "abc-123",
    "version": "v1"
  }
}

Authentication

Every authenticated request must include a valid JWT token:

Authorization: Bearer <access_token>

The gateway extracts the tenant_id claim from the JWT and injects it as the X-Tenant-ID header for downstream services.

Content Type

All request and response bodies use JSON:

Content-Type: application/json
Accept: application/json

Gateway Routing

The Kong API Gateway routes requests to backend services based on URL prefix:

Related Sections

• Data Flow -- Request lifecycle through the API layer
• Service Topology -- Service communication patterns
• Security: Authentication -- Full authentication architecture