rest-best-practices

name	rest-best-practices
description	REST conventions tuned for mobile clients -- resources, HTTP caching, idempotency, and versioning. Use when designing or reviewing RESTful endpoints.

REST Best Practices for Mobile

Instructions

REST for mobile is less about purity and more about predictability. Mobile apps retry, reconnect, and live across months of OS and app updates. Follow these rules so the contract ages well.

1. Resource-Oriented URLs

Model real things. Avoid verbs in paths.

• Good: POST /v1/orders, GET /v1/orders/{id}, POST /v1/orders/{id}/cancel
• Bad: POST /v1/createOrder, GET /v1/getOrderById?id=...

Sub-actions that do not map to CRUD (e.g., cancel, retry, approve) get a sub-resource with POST: POST /v1/orders/{id}/cancel. The body may be empty or carry context (reason codes).

2. HTTP Method Semantics

Method	Safe	Idempotent	Typical use
GET	yes	yes	read
HEAD	yes	yes	metadata
PUT	no	yes	full replace
PATCH	no	no (usually)	partial update
DELETE	no	yes	remove
POST	no	no	create / action

Use PATCH with JSON Merge Patch (RFC 7396) for partial updates; document semantics explicitly.

3. Status Codes

Use a small, consistent set. Do not invent 4xx meanings.

• 200 OK -- successful read or action with body.
• 201 Created -- resource created; include Location header and the created entity in the body.
• 202 Accepted -- async work queued; body holds a job id / status URL.
• 204 No Content -- successful mutation with no body.
• 400 INVALID_REQUEST / 422 VALIDATION_FAILED -- bad shape vs bad values.
• 401 UNAUTHENTICATED / 403 FORBIDDEN -- identity vs authorization.
• 404 NOT_FOUND, 409 CONFLICT, 410 GONE.
• 412 PRECONDITION_FAILED with If-Match etag mismatch.
• 429 RATE_LIMITED with Retry-After.
• 5xx -- server bugs or dependencies.

4. Caching

Turn caching on, deliberately.

Cache-Control: private, max-age=60, stale-while-revalidate=120
ETag: "v42-abc"
Last-Modified: Sun, 12 Apr 2026 10:00:00 GMT

Clients revalidate with If-None-Match: "v42-abc"; server returns 304 Not Modified without a body on miss. Save bytes and battery.

Server example (Go, net/http):

func getArticle(w http.ResponseWriter, r *http.Request) {
    a, etag, err := store.Get(r.PathValue("id"))
    if err != nil { httpError(w, err); return }
    if match := r.Header.Get("If-None-Match"); match == etag {
        w.WriteHeader(http.StatusNotModified); return
    }
    w.Header().Set("ETag", etag)
    w.Header().Set("Cache-Control", "private, max-age=60")
    json.NewEncoder(w).Encode(a)
}

Client (Swift, URLSession): the system cache honors ETag when URLRequest.cachePolicy is .useProtocolCachePolicy and URLSessionConfiguration.urlCache is set.

5. Idempotency

PUT and DELETE are idempotent by spec. POST is not -- add an Idempotency-Key header on every POST that creates or charges.

POST /v1/payments
Idempotency-Key: 01HX7MJ4Z7SD6N8Q4QB4J8YD3M
Content-Type: application/json

Server stores (key, request_hash) -> response with TTL ≥ 24 h. Replays return the stored response; body mismatch returns 409 IDEMPOTENCY_KEY_CONFLICT. See the token-strategy skill for UUID/ULID generation on clients.

6. Versioning

Use a URL major version (/v1/). Within a major, evolve additively: new optional fields, new endpoints, new enum values. Breaking changes get /v2/.

• Deprecation window ≥ 6 months.
• Emit Deprecation: true and Sunset: <http-date> headers on deprecated endpoints.
• Document every change in a machine-readable OpenAPI diff.

7. Concurrency Control

For editable resources, round-trip the ETag:

GET  /v1/profile              -> ETag: "v7"
PATCH /v1/profile
If-Match: "v7"

On mismatch, reply 412 PRECONDITION_FAILED. The client fetches the latest version, re-applies the edit, and retries.

8. Long-Running Operations

Return 202 Accepted with a pointer:

{ "job_id": "job_01HX7...", "status_url": "/v1/jobs/job_01HX7..." }

Clients poll the status URL with exponential backoff (see rate-limiting skill) or subscribe via WebSocket if available.

Checklist

• URLs are noun-based; verbs only on action sub-resources.
• Status codes follow the table above; error codes in the body envelope.
• ETag / Cache-Control set on cacheable reads; If-None-Match returns 304.
• Idempotency-Key accepted and persisted on all non-idempotent POSTs.
• URL-based major versioning with deprecation/sunset headers.
• If-Match supported on mutations of editable resources.
• Long-running work returns 202 with a polling/streaming pointer.