API Design Basics

9 examples for HTTP API design in Rust services - 6 basic and 3 intermediate.

Prerequisites

[dependencies]
axum = "0.8"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Patterns here apply across Axum, Actix, and tonic HTTP gateways.
Pair with serde DTOs at the HTTP boundary.

Basic Examples

1. Resource URLs

Nouns in paths, verbs in HTTP methods.

GET    /users
POST   /users
GET    /users/{id}
PATCH  /users/{id}
DELETE /users/{id}

Plural resource names.
Avoid RPC-style /createUser for CRUD.
Nest sub-resources: /users/{id}/orders.

Related: GraphQL in Rust - alternative query model

2. Status Codes

Map outcomes to HTTP semantics.

201 Created     - POST success with resource
204 No Content  - DELETE success
409 Conflict    - duplicate unique field
422 Unprocessable Entity - validation failure

Do not return 200 for errors.
401 unauthenticated vs 403 forbidden.
429 when rate limited.

3. Error Envelope

Stable machine-readable errors.

{"error":{"code":"invalid_email","message":"Email format invalid","field":"email"}}

Include code, message, optional field.
Log correlation ID server-side only.
Never expose stack traces.

Related: Input Validation & Injection - validation errors

4. Versioning

Explicit API versions.

/v1/users
Accept: application/vnd.example.v1+json

URL prefix is simplest for public APIs.
Document deprecation timelines.
Avoid silent breaking changes.

5. Pagination

Cursor-based listing.

GET /items?limit=20&cursor=eyJpZCI6MTB9

Prefer cursors over OFFSET on large tables.
Return next_cursor in response body.
Cap maximum limit.

6. Idempotency

Safe retries for POST.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Store key + response hash in Redis or SQL.
Return same response on duplicate key within TTL.
Required for payment and create operations.

Related: Retries, Timeouts & Backoff - client retries

Intermediate Examples

7. Content Negotiation

JSON default with explicit content type.

// handlers return Json<T> - Axum sets application/json

Support Accept header if multi-format.
Document charset UTF-8 for JSON.

8. Problem Details (optional standard)

RFC 7807 application/problem+json for errors.

{"type":"https://api.example.com/errors/validation","title":"Validation failed","status":422}

Standard fields: type, title, status, detail.
Align with client SDK generators.

9. OpenAPI Metadata

Describe API for consumers.

// use utoipa::ToSchema on DTOs and utoipa::path on handlers

Keep OpenAPI generated from code where possible.
Publish at /docs only in non-prod or behind auth.

Related: APIs & Security Best Practices - full baseline

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

API Design Basics

9 examples for HTTP API design in Rust services - 6 basic and 3 intermediate.

Prerequisites

[dependencies]
axum = "0.8"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Patterns here apply across Axum, Actix, and tonic HTTP gateways.
Pair with serde DTOs at the HTTP boundary.

Basic Examples

1. Resource URLs

Nouns in paths, verbs in HTTP methods.

GET    /users
POST   /users
GET    /users/{id}
PATCH  /users/{id}
DELETE /users/{id}

Plural resource names.
Avoid RPC-style /createUser for CRUD.
Nest sub-resources: /users/{id}/orders.

Related: GraphQL in Rust - alternative query model

2. Status Codes

Map outcomes to HTTP semantics.

201 Created     - POST success with resource
204 No Content  - DELETE success
409 Conflict    - duplicate unique field
422 Unprocessable Entity - validation failure

Do not return 200 for errors.
401 unauthenticated vs 403 forbidden.
429 when rate limited.

3. Error Envelope

Stable machine-readable errors.

{"error":{"code":"invalid_email","message":"Email format invalid","field":"email"}}

Include code, message, optional field.
Log correlation ID server-side only.
Never expose stack traces.

Related: Input Validation & Injection - validation errors

4. Versioning

Explicit API versions.

/v1/users
Accept: application/vnd.example.v1+json

URL prefix is simplest for public APIs.
Document deprecation timelines.
Avoid silent breaking changes.

5. Pagination

Cursor-based listing.

GET /items?limit=20&cursor=eyJpZCI6MTB9

Prefer cursors over OFFSET on large tables.
Return next_cursor in response body.
Cap maximum limit.

6. Idempotency

Safe retries for POST.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Store key + response hash in Redis or SQL.
Return same response on duplicate key within TTL.
Required for payment and create operations.

Related: Retries, Timeouts & Backoff - client retries

Intermediate Examples

7. Content Negotiation

JSON default with explicit content type.

// handlers return Json<T> - Axum sets application/json

Support Accept header if multi-format.
Document charset UTF-8 for JSON.

8. Problem Details (optional standard)

RFC 7807 application/problem+json for errors.

{"type":"https://api.example.com/errors/validation","title":"Validation failed","status":422}

Standard fields: type, title, status, detail.
Align with client SDK generators.

9. OpenAPI Metadata

Describe API for consumers.

// use utoipa::ToSchema on DTOs and utoipa::path on handlers

Keep OpenAPI generated from code where possible.
Publish at /docs only in non-prod or behind auth.

Related: APIs & Security Best Practices - full baseline

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

API Design Basics

Buscar en la documentación

API Design Basics