REST APIs

01Resources and URLs

REST (Representational State Transfer) models your domain as resources: nouns such as products, orders and customers. Each resource has a URL; the method says what to do with it. Use plural nouns and IDs: /orders, /orders/1001, /orders/1001/items. Avoid verbs in paths such as /getOrders or /createOrder; the method already says that. Keep nesting shallow (one level is usually enough). For actions that do not map cleanly to CRUD, model them as sub-resources or state changes: POST /orders/1001/cancellation or PATCH /orders/1001 with a status field. Use consistent naming (camelCase or snake_case, pick one), ISO 8601 dates in UTC, and IDs that do not leak business volume where that matters. Analogy: resources are rooms in a building, URLs are their addresses, and methods are what you do in the room.

1GET    /v1/orders?status=pending&page=2   # list
2POST   /v1/orders                         # create
3GET    /v1/orders/1001                    # read one
4PATCH  /v1/orders/1001                    # partial update
5DELETE /v1/orders/1001                    # delete
6GET    /v1/customers/77/orders            # related collection
7POST   /v1/orders/1001/refunds            # action as sub-resource

02Methods, status codes and error format

Map operations to methods and results to status codes. Creating returns 201 Created with a Location header and the new resource. Success with no content returns 204. Validation errors return 422 (or 400 for malformed JSON) with field-level details. Not authenticated is 401, not allowed is 403, missing is 404, a version or state conflict is 409, too many requests is 429, and server bugs are 500. Pick one error format and use it everywhere. RFC 9457 Problem Details (application/problem+json) is a good standard: type, title, status, detail, plus your own fields such as errors per field and a request ID for support. Never leak stack traces or SQL in production errors.

1HTTP/1.1 422 Unprocessable Content
2Content-Type: application/problem+json
3 
4{
5  "type": "https://api.example.com/problems/validation",
6  "title": "The request has invalid fields.",
7  "status": 422,
8  "errors": { "quantity": ["Must be at least 1."] },
9  "requestId": "req_7f3a9c"
10}

03Pagination, filtering, sorting

Never return unbounded lists. Offset pagination (?page=3&per_page=20) is simple and lets users jump to a page, but gets slow on large tables and can skip or repeat items when data changes. Cursor pagination (?cursor=eyJpZCI6MTAwMH0&limit=20) uses an opaque pointer such as the last seen ID and created_at; it is fast and stable for feeds, infinite scroll and syncs, but cannot jump to page 50. Return metadata or links so clients do not build URLs themselves. For filtering use clear query parameters (?status=paid&created_from=2026-01-01), for sorting ?sort=-created_at,total, and for search ?q=. Cap the maximum page size and only allow filtering and sorting on indexed fields.

1GET /v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAyMH0
2 
3{
4  "data": [ { "id": 1019, "total": 12500, "status": "paid" } ],
5  "meta": { "limit": 20, "hasMore": true },
6  "links": { "next": "/v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwMH0" }
7}

04Versioning and evolving safely

Clients, especially mobile apps that users do not update, depend on your API for years. Additive changes are safe: new endpoints, new optional fields, new enum values if clients were told to tolerate unknown ones. Breaking changes include removing or renaming fields, changing types or meaning, and making optional input required. For breaking changes, introduce a new version. URL versioning (/v1, /v2) is the most visible and the easiest to route, cache and debug; header or media-type versioning keeps URLs clean but is harder to test. Some APIs use dated versions in a header. Whatever you choose, announce deprecations with dates, send Deprecation and Sunset headers, and track which clients still call old versions before turning them off. Pair this with a forced-update mechanism in mobile apps.

05Authentication, idempotency and rate limits

Pick auth by client type. Browser apps on the same site: secure HttpOnly session cookies plus CSRF protection. Mobile and SPA clients: short-lived access tokens (often JWT) with refresh tokens, via OAuth 2 flows with PKCE for third-party login. Server-to-server partners: scoped API keys or OAuth client credentials, sent in headers, never in URLs. Networks fail, so make writes safe to retry: clients send an Idempotency-Key header with a unique value; the server stores the key with the result and returns the same response if the key is repeated, instead of charging or ordering twice. Protect the API with rate limits per key, user or IP, answer 429 with Retry-After, and expose limits in headers so clients can slow down.

1POST /v1/payments HTTP/1.1
2Authorization: Bearer <access_token>
3Idempotency-Key: 6f1c2d4e-8a7b-4c3d-9e2f-1a2b3c4d5e6f
4Content-Type: application/json
5 
6{"orderId": 1001, "amount": 12500, "currency": "AMD"}
7 
8HTTP/1.1 429 Too Many Requests
9Retry-After: 30
10RateLimit-Policy: "default";q=100;w=60

06Documentation with OpenAPI

OpenAPI (version 3.1 is current and aligned with JSON Schema) describes your endpoints, parameters, request and response bodies, errors and auth in a YAML or JSON file. From that one source you get interactive docs (Swagger UI, Redoc, Scalar), generated typed clients for TypeScript, Kotlin or Swift, mock servers and contract tests. Generate it from code annotations or decorators (NestJS has built-in support; Laravel has packages such as Scramble) so it never drifts from reality. Add examples for every request and error, describe pagination and rate limits, and publish a changelog. Good docs are a feature: they cut integration time from weeks to days.

1paths:
2  /v1/orders/{id}:
3    get:
4      summary: Get one order
5      parameters:
6        - { name: id, in: path, required: true, schema: { type: integer } }
7      responses:
8        "200":
9          description: The order
10          content:
11            application/json:
12              schema: { $ref: "#/components/schemas/Order" }
13        "404": { $ref: "#/components/responses/NotFound" }

07REST vs GraphQL vs gRPC vs WebSockets vs webhooks

These solve different problems and often live side by side. REST is the default for public and mobile APIs: simple, cacheable, understood by every tool. GraphQL lets clients ask for exactly the fields they need from one endpoint, which helps when many different screens combine data from many sources; the cost is complex caching, authorization per field and query-cost limits. gRPC uses Protocol Buffers over HTTP/2 with generated clients and streaming; great for fast, typed service-to-service calls, awkward in browsers. WebSockets keep a two-way connection open for chat, live order status and dashboards. Webhooks are reverse APIs: your server calls the partner's URL when something happens, such as a payment succeeded; sign them with HMAC, retry with backoff and make receivers idempotent.

• Public, partner or mobile API: REST + OpenAPI.
• Many clients with very different data needs: consider GraphQL.
• Internal high-throughput services: gRPC.
• Live updates to users: WebSockets or SSE. Events to other systems: webhooks.

08Authorization is the number one API risk

The OWASP API Security Top 10 (2023) puts Broken Object Level Authorization first: the API checks that a user is logged in, but not that the order, invoice or file they ask for belongs to them, so changing /orders/1001 to /orders/1002 leaks someone else's data. Close behind are broken function-level authorization (a regular user calling an admin endpoint) and broken object property level authorization (mass assignment, where a client sets role or price in a PATCH body). The robust pattern is to scope every query by the caller, not to check afterwards: fetch through the user's or tenant's relationship, so a foreign ID simply finds nothing and returns 404. Whitelist writable fields per endpoint, and use policies or guards that run on every route. Random or prefixed IDs reduce guessing but never replace authorization.

1// Laravel: scope by owner, then authorize with a policy
2public function show(Request $request, int $id)
3{
4    $order = $request->user()->orders()->findOrFail($id); // 404 for others
5    $this->authorize('view', $order);
6    return new OrderResource($order);
7}
8 
9// Only allow known fields to be written
10$data = $request->validate([
11    'note'     => ['nullable', 'string', 'max:500'],
12    'quantity' => ['required', 'integer', 'min:1'],
13]);

09Long-running operations and reliable events

Some requests cannot finish within a normal timeout: exports, imports, video processing, bulk updates. Instead of holding the connection open, accept the work and return 202 Accepted with a Location header pointing to a status resource such as /v1/jobs/77. The client polls that resource, or subscribes to a webhook, and finally follows a link to the result. A related problem is publishing events reliably. If the code saves an order and then sends a webhook, a crash between the two steps loses the event; sending first and then failing to save creates a ghost event. The transactional outbox pattern fixes this: write the order and an outbox row in the same database transaction, and let a worker deliver outbox rows with retries. Consumers must still deduplicate by event ID, because delivery is at least once.

1POST /v1/exports HTTP/1.1
2Content-Type: application/json
3 
4{"type": "orders", "from": "2026-10-01", "to": "2026-10-31"}
5 
6HTTP/1.1 202 Accepted
7Location: /v1/jobs/77
8 
9GET /v1/jobs/77  ->  {"status": "running", "progress": 40}
10GET /v1/jobs/77  ->  {"status": "done", "resultUrl": "/v1/exports/77/file"}

10Rate limiting algorithms

A fixed window counts requests per calendar minute; it is simple but allows double bursts at the boundary (100 at 12:00:59 and 100 at 12:01:00). A sliding window weighs the previous window's count to smooth that out. A token bucket gives each client a bucket that refills at a steady rate up to a maximum, so short bursts are allowed while the long-term rate stays fixed; it matches how real clients behave. Store counters in Redis with atomic operations so all app servers share them. Choose keys carefully: per API key for partners, per user for logged-in traffic, per IP only as a last resort, since many users can share one IP behind a NAT or mobile carrier. Return 429 with Retry-After, and use separate, stricter limits for expensive or sensitive endpoints like search, login and exports.

1// Laravel: named limiters, applied with ->middleware('throttle:api')
2RateLimiter::for('api', function (Request $request) {
3    return $request->user()
4        ? Limit::perMinute(120)->by('user:'.$request->user()->id)
5        : Limit::perMinute(30)->by('ip:'.$request->ip());
6});
7 
8RateLimiter::for('login', fn (Request $request) =>
9    Limit::perMinute(5)->by($request->input('email').'|'.$request->ip())
10);

11Performance: payload shape, N+1 and caching

Most slow APIs are slow in the database. A list endpoint that loads 50 orders and then queries the customer for each one makes 51 queries: the N+1 problem. Eager-load relations, select only needed columns and add indexes that match filters and sort order; log query counts per request in development. Shape payloads for the client: sparse fieldsets (?fields=id,total,status) or include parameters (?include=customer) let one endpoint serve both a compact list and a detailed view. Compress JSON with gzip or Brotli. For read-heavy resources, send ETag or Last-Modified so clients get 304 responses, and cache computed responses in Redis with explicit invalidation on writes. Public, non-personal endpoints such as a product catalogue can be cached at a CDN with s-maxage. Measure p95 latency per endpoint, not averages.