Production-grade guide to platform api design patterns covering architecture patterns, implementation strategies, testing approaches, and operational best practices for enterprise engineering teams.
Platform API Design Patterns is a curated set of proven strategies for designing APIs that serve as foundational services across a platform. These patterns address recurring challenges in cross-team integration, developer onboarding, and operational consistency. They matter when a platform must support dozens of services and hundreds of developers, and when APIs must evolve independently while remaining predictable and reliable.
When an API call fails, the caller must understand *why* and *how* to recover. A consistent error shape enables tooling, monitoring, and client libraries to handle failures uniformly.
The API should return a standardized error object in the response body, with at least the following fields:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "One or more fields failed validation",
"details": [
{
"field": "email",
"message": "Must be a valid email address",
"value": "jane@com"
},
{
"field": "age",
"message": "Must be greater than 18",
"value": 16
}
],
"timestamp": "2024-03-15T12:34:56Z",
"request_id": "req-8a3c2f1d"
}
}The code field is a machine-readable identifier that maps to a known failure type. The details array provides per-field or per-validation context. The request_id enables tracing across services.
Clients should expect HTTP status codes to reflect *semantic* meaning:
400 Bad Request for client-side issues (invalid input, missing fields).401 Unauthorized when authentication fails.403 Forbidden when the authenticated user lacks permission.404 Not Found for resources that do not exist.429 Too Many Requests for rate-limiting.500 Internal Server Error for unexpected server failures.A common failure: clients only check status === 500, but the API returns 503 Service Unavailable for temporary outages. The client must handle 5xx as transient errors and retry with exponential backoff. The details field is often omitted, causing teams to write ad-hoc error-handling logic that diverges across services.
When a client sends a request that may be retried (e.g., over unreliable networks), the API must ensure that multiple identical requests produce the same result as a single request.
To enable idempotency, the client includes an Idempotency-Key header in the request:
POST /api/v1/orders HTTP/1.1
Host: api.platform.example
Content-Type: application/json
Idempotency-Key: 9a2f1d3c-4b5e-6f7a-8b9c-0d1e2f3a4b5c
Authorization: Bearer abc123
{
"customer_id": 123,
"items": [
{ "product_id": 456, "quantity": 2 }
]
}The server stores the Idempotency-Key in a database (e.g., a idempotency_keys table with key, request_body, response, created_at, expires_at). On receiving a request, the server checks if the key already exists. If so, it returns the stored response (without reprocessing). If not, it processes the request, stores the response, and returns it.
The response includes a Idempotency-Result header:
Idempotency-Result: fresh if the request was processed.Idempotency-Result: cached if the result was reused.Clients must send Idempotency-Key on every idempotent operation, especially on POST, PUT, and PATCH. A common mistake is using Idempotency-Key only on POST, but forgetting to include it on PUT or PATCH, leading to duplicate updates or inconsistent state.
If the Idempotency-Key expires (e.g., after 1 hour), the server may allow reprocessing of the same key within the window, and clients must handle Idempotency-Result: cached as a signal that the data is stale.
As platforms grow, APIs evolve. Versioning ensures backward compatibility and enables gradual migration.
The platform uses URL-based versioning: https://api.platform.example/v1/users, https://api.platform.example/v2/users. Clients may also use the Accept header to negotiate versioning:
GET /api/v1/users/123 HTTP/1.1
Host: api.platform.example
Accept: application/vnd.platform.v2+jsonThe server returns data with a Content-Type: application/vnd.platform.v2+json.
Each version must be independent. When a new version is released, the old version continues to serve requests. A change in v1 (e.g., adding a phone field to the user object) does not break v2, which may have added preferences and removed settings.
Clients should send a User-Agent header indicating the API version they expect:
User-Agent: MyApp/1.4.0 (API v2)The server uses this to provide version-specific error messages and to track adoption.
A sharp edge: clients forget to include Accept or User-Agent, leading to inconsistent behavior. The v1 API returns settings as a string, but v2 returns it as an object. Clients that assume settings is an object fail when calling v1, but work correctly with v2. The platform must document which fields are stable across versions, and which are experimental.
For APIs returning large result sets, pagination is essential. The platform uses cursor-based pagination (also known as "offset-based with tokens"), which enables efficient, consistent, and scalable navigation.
Clients request data with a cursor and limit query parameters:
GET /api/v1/events?cursor=abc123&limit=50 HTTP/1.1
Host: api.platform.example
Accept: application/jsonThe server returns a response with a next_cursor and has_next field:
{
"data": [
{ "id": 1, "name": "Deploy v1.0", "timestamp": "2024-03-15T10:00:00Z" },
{ "id": 2, "name": "Rollback", "timestamp": "2024-03-14T15:30:00Z" }
],
"pagination": {
"next_cursor": "def456",
"has_next": true,
"limit": 50,
"total": 1200
}
}The next_cursor is a base64-encoded token derived from the last item in the result set. The server uses this token to resume the query from that point. The has_next field indicates whether more results are available.
Clients must follow the next_cursor in the Link HTTP header:
Link: <https://api.platform.example/v1/events?cursor=def456&limit=50>; rel="next"When the client fetches the next page, it sends the next_cursor as the cursor query parameter.
A common failure: clients use limit but ignore next_cursor, leading to missing or duplicated results. Another: the server uses offset but returns cursor, and the client uses offset for the next request, causing inconsistent results.
The platform must ensure that the cursor value is stable across writes. If an event is created while fetching, the cursor must be updated to reflect the new position. The cursor should include both the primary key and a timestamp or version to handle concurrent updates.
To ensure that APIs remain consistent across teams, the platform adopts a contract-first approach using a schema registry.
Each API defines its request and response schemas in JSON Schema. The registry stores these schemas under a unique identifier, such as user.create.v1, event.created.v2.
Clients generate code from the schema using tools like ajv, json-schema-to-typescript, or openapi-generator. The platform enforces schema validation at build and deployment.
A typical openapi.yaml file:
openapi: 3.0.3
info:
title: User Management API
version: v1
servers:
- url: https://api.platform.example/v1
paths:
/users:
post:
summary: Create a new user
requestBody:
$ref: '#/components/requestBodies/CreateUser'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
requestBodies:
CreateUser:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserInput'
schemas:
CreateUserInput:
type: object
required: [ name, email ]
properties:
name:
type: string
minLength: 1
email:
type: string
format: email
phone:
type: string
pattern: '^\\+?[1-9]\\d{9,14}$'
metadata:
type: object
additionalProperties: true
User:
type: object
required: [ id, name, email, created_at ]
properties:
id:
type: integer
format: int64
name:
type: string
email:
type: string
phone:
type: string
metadata:
type: object
additionalProperties: true
created_at:
type: string
format: date-timeThe platform validates every API request against the schema. If the request body does not conform to CreateUserInput, the server returns a 400 Bad Request with a detailed error:
{
"error": {
"code": "SCHEMA_VALIDATION_FAILED",
"message": "Request body failed schema validation",
"details": [
{
"field": "email",
"message": "Must be a valid email address",
"value": "jane@com"
},
{
"field": "phone",
"message": "Phone must match pattern ^\\+?[1-9]\\d{9,14}$",
"value": "+123"
}
]
}
}The platform enforces backward compatibility: when a new version of a schema is published, the old version remains available, and clients may pin to a specific version.
A sharp edge: schema changes are not versioned in the openapi.yaml file, leading to clients using the wrong schema. The platform must version the schema independently of the API version, and the openapi.yaml file must include a schemaVersion field.
APIs must be secured using a consistent authentication mechanism. The platform uses OAuth 2.0 with Bearer tokens, and supports fine-grained authorization via scopes and roles.
Clients authenticate with a Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yVq97kC35d2AThe server validates the token and extracts claims such as sub, name, email, roles, and scopes.
The platform supports two authorization models:
read:users, write:events, admin).viewer, editor, admin, superadmin).A client may request a token with multiple scopes:
GET /api/v1/users?scope=read:users,write:events HTTP/1.1
Host: api.platform.example
Authorization: Bearer abc123The server checks that the token includes all required scopes and returns 403 Forbidden with a detailed error if any scope is missing.
Clients often confuse scope and roles. The platform must document which endpoints require which scope, and which roles grant access. The roles claim in the JWT is used for role-based access control, while scopes are used for fine-grained, feature-level permissions.
A common failure: clients send the Authorization header but forget to include the scope or roles claims in the token, leading to silent permission failures. The platform logs missing scopes and sends alerts when a service is accessed by a user without required permissions.
For real-time and asynchronous workflows, the platform uses event-driven APIs.
Services emit events as JSON payloads to a message broker (e.g., Kafka, RabbitMQ). The platform defines a standard event schema:
{
"event_id": "evt-1a2b3c4d",
"event_type": "user.created.v1",
"source": "user-service",
"timestamp": "2024-03-15T12:34:56.789Z",
"data": {
"user_id": 123,
"name": "Jane Doe",
"email": "[email protected]"
}
}The event_type is a globally unique identifier (e.g., user.created.v1, order.processed.v2). Services consume events using a standard consumer interface, such as a POST /events endpoint or a Kafka consumer group.
Clients publish events using curl:
curl -X POST https://api.platform.example/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer abc123" \
-d '{
"event_type": "user.created.v1",
"data": {
"user_id": 123,
"name": "Jane Doe",
"email": "[email protected]"
}
}'The platform ensures idempotent event processing: each event is processed exactly once, even across service restarts.
A sharp edge: event types are not registered in the platform, leading to mismatched event types. The platform must maintain a registry of event types, including their schema, version, and consumer list.
Clients often send events without event_id, leading to duplicate processing. The platform must require event_id and use it as a deduplication key.
This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.
We use cookies for analytics (Google Analytics) and advertising (Google AdSense) to improve your experience and support free content. Privacy Policy