REST API Guidelines

REST API Design Guidelines

Opinionated guidance for designing consistent, developer-friendly REST APIs. Apply these guidelines when designing new APIs or reviewing existing API designs.

URL Structure

Pattern: /{serviceRoot}/{collection}/{id}

URLs should be human-readable and hierarchical:

• https://api.example.com/v1/people/jdoe@example.com/inbox
• https://api.example.com/v1/orders/12345/items

Rules:

• Collection names: unabbreviated, pluralized nouns (/users, /orders, /messages)
• Use path segments for hierarchy, not query parameters
• Keep URLs short and predictable
• Resources that can move or rename should expose stable identifier URLs

URL length: Design for under 2,083 characters to accommodate all clients.

HTTP Methods

PATCH for UPSERT:

• Without precondition headers: service determines create vs. update
• With If-Match: update only (409 if missing)
• With If-None-Match: *: create only (409 if exists)

Status Codes

Success

Client Errors

Server Errors

Important: Rate-limit failures (429) are client errors, not faults. Only 5xx errors count as faults affecting availability.

Error Response Format

All error responses use a single JSON object with a mandatory error property:

{
  "error": {
    "code": "BadArgument",
    "message": "Human-readable description for developers",
    "target": "propertyName",
    "details": [],
    "innererror": {}
  }
}

Error Object Properties

Nested Error Example

{
  "error": {
    "code": "BadArgument",
    "message": "Previous passwords may not be reused",
    "target": "password",
    "innererror": {
      "code": "PasswordError",
      "innererror": {
        "code": "PasswordDoesNotMeetPolicy",
        "minLength": "6",
        "maxLength": "64"
      }
    }
  }
}

Multiple Errors Example

{
  "error": {
    "code": "BadArgument",
    "message": "Multiple validation errors",
    "details": [
      { "code": "NullValue", "target": "phoneNumber", "message": "Phone number is required" },
      { "code": "NullValue", "target": "lastName", "message": "Last name is required" }
    ]
  }
}

Rules:

• Changing visible code values is a breaking change
• Use innererror for new granular codes without breaking clients
• Clients should traverse innererror chain and act on the deepest understood code
• Include Retry-After header for transient errors

Collections and Pagination

Collection Representation

Wrap collections in a value property:

{
  "value": [
    { "id": "1", "name": "Item One" },
    { "id": "2", "name": "Item Two" }
  ]
}

Empty collections return 200 OK with empty array:

{
  "value": []
}

Server-Driven Pagination

Include a continuation token as @nextLink (an opaque URL):

{
  "value": [ ... ],
  "@nextLink": "https://api.example.com/v1/people?$skip=20"
}

• Absence of @nextLink indicates the final page
• Clients must treat continuation URLs as opaque — no modification

Client-Driven Pagination

Server applies $skip first, then $top. The server must return an error if it cannot honor the parameters (never silently ignore them).

Page Size Preference

Clients may specify $maxpagesize as a preferred page size. Servers should honor it if smaller than the server default.

Use $count=true to include total item count across all pages.

Filtering

Parameter: $filter

Boolean expression evaluated for each resource. Only items where the expression is true are included.

Operators

Operator Precedence (highest to lowest)

1. ( ) — Grouping
2. not — Unary
3. gt, ge, lt, le — Relational
4. eq, ne — Equality
5. and — Conditional AND
6. or — Conditional OR

Sorting

Parameter: $orderBy

Default direction is ascending. NULL values sort before non-NULL values.

Sorting composes with filtering: GET /people?$filter=status eq 'active'&$orderBy=name

If the server doesn't support sorting by a requested property, return an error.

Versioning

All APIs must support explicit versioning.

Format: Major.Minor (e.g., 1.0, 2.1)

Two mechanisms:

1. URL path (recommended): https://api.example.com/v1/products
2. Query parameter: https://api.example.com/products?api-version=1.0

When to version:

• Major increment: breaking changes (signals future deprecation of previous version)
• Minor increment: non-breaking additions

Breaking changes include:

• Removing or renaming APIs or parameters
• Changing behavior of existing APIs
• Changing error codes or fault contracts

Documentation: indicate support status of each previous version and the path to the latest.

Naming Conventions

JSON Properties

Use camelCase for all JSON property names:

• firstName, lastName, dateOfBirth
• Not: first_name, FirstName, FIRST_NAME

Common Property Names

Date/Time Properties

Use ISO 8601 format: 2025-02-13T13:15:00Z

Suffixes: Date, Time, DateTime, Timestamp

• createdDate, lastModifiedTime, expirationDateTime

Collections

• Collection names: plural nouns (addresses, orders)
• Count properties: count suffix (addressCount)

General Rules

• Use full words, not abbreviations (emailAddress not email_addr)
• Avoid acronyms without context
• Avoid language-specific keywords

CORS (Cross-Origin Resource Sharing)

All APIs should support CORS.

For every request with an Origin header:

1. Return Access-Control-Allow-Origin echoing the request's Origin value
2. Include Access-Control-Expose-Headers listing non-simple response headers
3. Set Access-Control-Allow-Credentials: true if cookies are required

For OPTIONS preflight requests, additionally include:

• Access-Control-Allow-Headers: permitted request headers
• Access-Control-Allow-Methods: permitted HTTP methods
• Access-Control-Max-Age: how long the preflight response is cached (in seconds)

Return 200 OK for preflight requests with no additional processing.

Authorization strategy: enforce authorization through valid tokens, not origin validation.

Throttling and Rate Limiting

Response Codes

Response Headers

Example 429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 1800

Design Principles

• Respond quickly with errors when overloaded — don't let requests hang
• Document rate limits and quota scopes (per user, per application, per IP)
• Rate-limit failures (429) must not count as faults in availability metrics

Client Behavior

• Respect Retry-After header
• Implement exponential backoff
• Cache responses where appropriate
• Design for graceful degradation under rate limits

Webhooks

Subscription Model

Clients create subscriptions for specific resource changes:

POST https://api.example.com/v1/subscriptions
Content-Type: application/json

{
  "notificationUrl": "https://client.example.com/webhook",
  "resource": "/users/123/messages",
  "changeType": "created,updated,deleted",
  "clientState": "client-context-value"
}

Subscription Management

Subscription Verification (Handshake)

When a subscription is created:

1. Service sends POST to notificationUrl with validationToken query parameter
2. Client responds with 200 OK and echoes the token in the response body (text/plain)
3. Service activates the subscription only after successful validation

This prevents malicious subscription creation to third-party endpoints.

Notification Payload

{
  "value": [
    {
      "subscriptionId": "sub-123",
      "clientState": "client-context-value",
      "changeType": "created",
      "resource": "/users/123/messages/456",
      "resourceData": {
        "id": "456"
      },
      "sequenceNumber": 1
    }
  ]
}

Reliability

• Services should retry delivery with backoff
• Notifications should be delivered in order (best-effort)
• Clients must handle duplicate deliveries (idempotency)

Security

• HTTPS only for webhook endpoints
• Services should include HMAC signature in headers (e.g., X-Webhook-Signature: sha256=...)
• Clients should validate signatures using the shared secret
• clientState provides additional verification that the notification originated from the expected service

Long-Running Operations

For operations expected to take more than 0.5 seconds (99th percentile):

1. Return 202 Accepted with Operation-Location header
2. Client polls the operation status URL
3. Operation resource reports status: notStarted, running, succeeded, failed

{
  "createdDateTime": "2025-02-13T12:01:03Z",
  "lastActionDateTime": "2025-02-13T12:06:03Z",
  "status": "running",
  "percentComplete": 45,
  "resourceLocation": "https://api.example.com/v1/exports/export-789"
}

Include Retry-After header to indicate polling interval.

Client Behavior Rules

1. Ignore unknown fields: clients must safely ignore unexpected response properties
2. Don't assume field order: JSON property order is not guaranteed
3. Handle graceful degradation: optional server features may not be available
4. Support pagination: handle both server-driven and client-driven paging
5. Implement backoff: exponential backoff for rate-limited retries
6. Validate webhooks: verify signatures and handle duplicates