APIAPIs

Thuộc bộ kiến thức Backend Roadmap.

Tổng quan

API (Application Programming Interface) là một bản hợp đồng (contract) cho phép một phần mềm giao tiếp với phần mềm khác. Nó định nghĩa bạn có thể yêu cầu điều gì, yêu cầu như thế nào, và nhận lại được gì — trong khi giấu đi phần implementation phía sau ranh giới đó. Với backend engineer, “API” gần như luôn có nghĩa là web API: một tập các operation được expose qua mạng (thường là HTTP) để browser, mobile app, các service khác và third-party developer có thể sử dụng khả năng cùng dữ liệu của hệ thống bạn.

Một API tốt là một sản phẩm, không phải thứ nghĩ sau. Nó là bề mặt mà consumer thực sự phụ thuộc vào, và một khi đã public thì rất khó thay đổi. Các họ API phổ biến bạn sẽ gặp là REST, GraphQL, gRPC, và SOAP (legacy). Mỗi loại có những đánh đổi khác nhau về transport, định dạng dữ liệu, mức độ coupling, streaming và tooling. Chọn đúng — và thiết kế contract một cách có chủ đích — là một trong những quyết định có đòn bẩy cao nhất trong công việc backend.

API-first design

API-first nghĩa là bạn thiết kế và thống nhất về API contract trước khi viết code implementation. Contract (một tài liệu OpenAPI, một GraphQL schema, một file .proto) trở thành single source of truth để các team frontend, backend và QA làm việc song song. Lợi ích:

• Phát triển song song — client có thể generate stub và mock server từ contract trong khi backend còn đang xây dựng.
• Tính nhất quán — một bộ từ vựng và quy ước chung xuyên suốt các team và service.
• Tooling — code generation, mock server, contract test và tài liệu đều sinh ra từ spec.
• Ít bất ngờ gây breaking — contract được review và version hóa như mọi tài sản quan trọng khác.

Phần lớn web API hiện đại trao đổi bằng JSON vì nó dễ đọc với con người, phổ biến khắp nơi và native với JavaScript. Các định dạng binary như Protocol Buffers đánh đổi khả năng đọc để lấy sự gọn nhẹ và tốc độ.

Kiến thức nền tảng

Vòng đời request/response trên HTTP

Gần như mọi web API đều chạy trên HTTP. Một request mang theo một method (verb), một URL/path, các header (metadata như Content-Type, Authorization, Accept), và một body tùy chọn. Response mang theo một status code, các header, và một body tùy chọn.

POST /v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

{ "productId": "sku_123", "quantity": 2 }

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/orders/ord_789

{ "id": "ord_789", "status": "pending", "total": 49.98 }

HTTP methods

Method	Mục đích	Safe	Idempotent
GET	Đọc một resource	Có	Có
POST	Tạo resource / action không idempotent	Không	Không
PUT	Thay thế toàn bộ resource	Không	Có
PATCH	Cập nhật một phần resource	Không	Không*
DELETE	Xóa một resource	Không	Có
HEAD	Giống GET nhưng chỉ trả header	Có	Có
OPTIONS	Khám phá method được phép (dùng bởi CORS preflight)	Có	Có

*PATCH có thể được làm cho idempotent tùy vào ngữ nghĩa của patch.

Safe = không thay đổi state phía server. Idempotent = gọi cùng một request N lần cho hiệu ứng giống hệt như gọi một lần.

HTTP status codes

Nhóm	Ý nghĩa	Ví dụ thường gặp
2xx	Thành công	200 OK, 201 Created, 202 Accepted, 204 No Content
3xx	Redirect	301 Moved Permanently, 304 Not Modified
4xx	Lỗi client	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
5xx	Lỗi server	500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout

Dùng status code cho chính xác: 401 nghĩa là “chưa authenticate”, 403 nghĩa là “đã authenticate nhưng không được phép”, 404 giấu đi sự tồn tại, 409 báo hiệu xung đột (ví dụ version mismatch), 422 nghĩa là payload đã hiểu được nhưng không hợp lệ về mặt ngữ nghĩa.

Khái niệm chính

REST

REST (Representational State Transfer) là một architectural style được Roy Fielding định nghĩa trong luận án năm 2000 của ông. Nó không phải là một protocol hay một standard — nó là một tập các ràng buộc (constraint) mà khi tuân theo sẽ tạo ra các hệ thống có khả năng mở rộng, dễ tiến hóa và loosely-coupled. Các constraint cốt lõi gồm: client–server, statelessness, cacheability, uniform interface, layered system, và tùy chọn code-on-demand.

Resource và representation

REST mô hình hóa domain thành các resource — những danh từ được định danh bằng URI. Một resource có một hoặc nhiều representation (thường là JSON). Thiết kế URL xoay quanh resource, không phải action:

GET    /v1/users              # liệt kê users
POST   /v1/users              # tạo một user
GET    /v1/users/42           # lấy user 42
PUT    /v1/users/42           # thay thế user 42
PATCH  /v1/users/42           # cập nhật một phần user 42
DELETE /v1/users/42           # xóa user 42
GET    /v1/users/42/orders    # liệt kê order thuộc về user 42

Dùng danh từ số nhiều cho collection, lồng sub-resource ở mức nông, và tránh verb trong path (/getUser, /createOrder là anti-pattern).

Statelessness

Mỗi request phải chứa mọi thứ server cần để xử lý nó — server không giữ session state của client giữa các request. Thông tin authentication đi kèm mỗi request (ví dụ một Bearer token). Chính statelessness cho phép bất kỳ server instance nào phía sau load balancer đều có thể xử lý bất kỳ request nào, tạo điều kiện cho horizontal scaling.

HATEOAS và Richardson Maturity Model

HATEOAS (Hypermedia As The Engine Of Application State) là constraint bị bỏ qua nhiều nhất của REST: response bao gồm các link cho client biết nó có thể làm gì tiếp theo, nhờ đó client điều hướng API bằng cách đi theo link thay vì hard-code URL.

{
  "id": "ord_789",
  "status": "pending",
  "total": 49.98,
  "_links": {
    "self":   { "href": "/v1/orders/ord_789" },
    "cancel": { "href": "/v1/orders/ord_789/cancel", "method": "POST" },
    "pay":    { "href": "/v1/orders/ord_789/payment", "method": "POST" }
  }
}

Richardson Maturity Model chấm điểm mức độ “RESTful” của một API:

Level	Tên	Mô tả
0	The Swamp of POX	Một URI, một verb (thường là POST) — RPC trên HTTP
1	Resources	Nhiều URI (resource), vẫn một verb
2	HTTP Verbs	Dùng đúng method + status code (nơi phần lớn API “REST” đang ở)
3	Hypermedia	HATEOAS — link điều khiển các chuyển đổi trạng thái

Versioning

API tiến hóa; versioning bảo vệ consumer hiện tại khỏi các breaking change. Các chiến lược phổ biến:

• URI path — /v1/users, /v2/users (phổ biến nhất, dễ thấy nhất).
• Header — Accept: application/vnd.example.v2+json (URL sạch hơn, khó test trên browser hơn).
• Query param — /users?version=2 (đơn giản nhưng làm rối query).

Chỉ tăng version cho các thay đổi breaking; các thay đổi mang tính bổ sung (field optional mới, endpoint mới) nên backward compatible.

Pagination, filtering, sorting

Đừng bao giờ trả về một list không giới hạn. Các kiểu pagination phổ biến:

• Offset/limit — GET /users?limit=20&offset=40. Đơn giản, nhưng chậm và không nhất quán trên dataset lớn, hay thay đổi.
• Cursor/keyset — GET /users?limit=20&cursor=eyJpZCI6NDJ9. Ổn định và nhanh cho infinite scroll; cursor mã hóa vị trí.

{
  "data": [ { "id": 41 }, { "id": 42 } ],
  "pagination": {
    "limit": 20,
    "nextCursor": "eyJpZCI6NjJ9",
    "hasMore": true
  }
}

Filtering và sorting qua query param: GET /orders?status=paid&sort=-createdAt&minTotal=100.

Idempotency

Với các operation không idempotent (như POST thanh toán), hãy để client gửi một idempotency key để request bị retry không tạo ra bản ghi trùng lặp:

POST /v1/payments
Idempotency-Key: 5f3a9c2e-...

{ "amount": 4998, "currency": "usd" }

Server lưu key cùng với kết quả; một request lặp lại với cùng key sẽ trả về response gốc thay vì charge hai lần. Đây là cách Stripe và nhiều bên khác làm cho retry trở nên an toàn.

Ví dụ JSON đầy đủ

GET /v1/products?category=books&limit=2 HTTP/1.1
Accept: application/json

{
  "data": [
    {
      "id": "prd_1",
      "name": "Clean Architecture",
      "price": { "amount": 3499, "currency": "usd" },
      "inStock": true
    },
    {
      "id": "prd_2",
      "name": "Designing Data-Intensive Applications",
      "price": { "amount": 5499, "currency": "usd" },
      "inStock": false
    }
  ],
  "pagination": { "limit": 2, "nextCursor": "eyJpZCI6InByZF8yIn0", "hasMore": true }
}

GraphQL

GraphQL là một query language và runtime cho API, được tạo tại Facebook và hiện thuộc GraphQL Foundation. Thay vì nhiều endpoint, nó expose một endpoint duy nhất và một schema có kiểu chặt chẽ (strongly-typed); client yêu cầu chính xác các field cần thiết trong một round trip.

Schema

Schema chính là contract, được viết bằng SDL (Schema Definition Language):

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
}

enum OrderStatus { PENDING PAID CANCELLED }

type Query {
  user(id: ID!): User
  users(limit: Int = 20): [User!]!
}

type Mutation {
  createOrder(userId: ID!, productId: ID!): Order!
}

type Subscription {
  orderStatusChanged(orderId: ID!): Order!
}

• Query — các operation đọc.
• Mutation — các operation ghi.
• Subscription — một stream cập nhật tồn tại lâu (thường qua WebSocket) cho dữ liệu real-time.

Query và resolver

Một query yêu cầu một hình dạng chính xác; response phản chiếu đúng hình dạng đó:

query GetUserWithOrders {
  user(id: "42") {
    name
    email
    orders {
      id
      total
      status
    }
  }
}

{
  "data": {
    "user": {
      "name": "Ada",
      "email": "ada@example.com",
      "orders": [
        { "id": "ord_1", "total": 49.98, "status": "PAID" }
      ]
    }
  }
}

Mỗi field được backing bởi một resolver — một hàm trả về dữ liệu cho field đó. Các resolver kết hợp với nhau: field orders trên User được resolve bởi một hàm riêng, hàm này nhận User cha làm tham số.

Over-fetching, under-fetching và N+1

Điểm bán hàng chính của GraphQL là loại bỏ over-fetching (lấy về những field bạn không cần) và under-fetching (phải gọi nhiều REST call để ghép nên một màn hình). Client chỉ định chính xác cây dữ liệu nó muốn.

Cạm bẫy kinh điển của GraphQL là N+1 problem: resolve một list N user rồi resolve orders cho từng user sẽ bắn 1 query cho user cộng thêm N query cho order của họ. Cách khắc phục chuẩn là DataLoader — nó gom (batch) N lượt tra cứu theo từng item thành một query gom chung và cache trong phạm vi một request.

// Không batch: 1 + N query
// Với DataLoader: 1 (users) + 1 (orders đã gom) query
const orderLoader = new DataLoader(async (userIds) => {
  const rows = await db.orders.whereIn('userId', userIds);
  return userIds.map((id) => rows.filter((r) => r.userId === id));
});

Đánh đổi REST vs GraphQL

GraphQL tỏa sáng với các UI hướng client, nặng về tổng hợp dữ liệu (mobile app, dashboard). Chi phí: HTTP caching khó hơn (mọi thứ là POST tới một endpoint), độ phức tạp của query phải bị giới hạn để tránh lạm dụng, và server phức tạp hơn. REST giữ cho CRUD đơn giản luôn đơn giản và tận dụng HTTP caching miễn phí.

gRPC

gRPC là một RPC framework hiệu năng cao từ Google, dùng Protocol Buffers (protobuf) cho schema/serialization và HTTP/2 cho transport. Bạn định nghĩa service và message trong một file .proto, rồi generate code client và server có kiểu chặt chẽ ở nhiều ngôn ngữ.

syntax = "proto3";
package shop.v1;

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc WatchOrders(WatchRequest) returns (stream Order); // server streaming
}

message GetOrderRequest { string id = 1; }

message Order {
  string id = 1;
  double total = 2;
  Status status = 3;
  enum Status { PENDING = 0; PAID = 1; CANCELLED = 2; }
}

Các đặc tính chính:

• Binary protobuf gọn hơn và (de)serialize nhanh hơn nhiều so với JSON.
• HTTP/2 mang lại multiplexing, header compression, và streaming native: unary, server-streaming, client-streaming và bidirectional-streaming.
• Code generation cho bạn stub type-safe ở cả hai đầu.

Khi nào dùng gRPC: giao tiếp service-to-service nội bộ trong backend microservices/đa ngôn ngữ, các đường (path) yêu cầu latency thấp và throughput cao, và các workload streaming. Khi nào không dùng: API public hướng browser (browser không nói được raw gRPC nếu không có gRPC-Web và một proxy), hoặc khi payload dễ đọc với con người và khả năng curl dễ dàng là quan trọng.

SOAP (legacy)

SOAP (Simple Object Access Protocol) là một protocol nhắn tin cũ hơn, dựa trên XML. Contract được mô tả bằng WSDL, message là các envelope XML, và nó mang theo một tập nặng các standard WS-* (WS-Security, WS-ReliableMessaging, v.v.). Nó transport-agnostic (thường là HTTP, đôi khi message queue) và strongly typed.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <getOrder xmlns="http://example.com/shop">
      <id>ord_789</id>
    </getOrder>
  </soap:Body>
</soap:Envelope>

Bạn sẽ chủ yếu gặp SOAP trong các hệ thống enterprise, ngân hàng và legacy của chính phủ. Với công việc mới, hãy ưu tiên REST, GraphQL hoặc gRPC — nhưng biết rằng SOAP tồn tại (và tại sao tính hình thức của nó từng có giá trị) vẫn hữu ích.

Tài liệu API và contract

OpenAPI / Swagger

OpenAPI (trước đây là Swagger) là specification chuẩn, không phụ thuộc ngôn ngữ, để mô tả các REST API. Một tài liệu YAML/JSON duy nhất mô tả path, method, parameter, schema request/response, auth và ví dụ. Từ nó bạn có thể generate tài liệu tương tác (Swagger UI), client SDK, server stub và contract test.

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
paths:
  /v1/orders/{id}:
    get:
      summary: Get an order by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Not found
components:
  schemas:
    Order:
      type: object
      properties:
        id:     { type: string }
        total:  { type: number, format: float }
        status: { type: string, enum: [pending, paid, cancelled] }
      required: [id, total, status]

Với GraphQL, chính schema là contract và cho phép tooling dựa trên introspection (GraphiQL, Apollo Studio). Với gRPC, file .proto là contract. Ở cả ba, contract có thể đọc được bằng máy — chứ không phải văn bản mô tả — mới là source of truth.

Các mối quan tâm xuyên suốt (cross-cutting)

Authentication và authorization

Mọi API không public đều cần biết ai đang gọi (authentication) và họ được phép làm gì (authorization). Các cơ chế phổ biến: API key, OAuth 2.0 / OpenID Connect, và JWT bearer token. Xem Authentication & Authorization và Web Security để đi sâu. Luôn truyền credential qua TLS và không bao giờ đặt trong URL.

CORS

CORS (Cross-Origin Resource Sharing) là một cơ chế bảo mật của browser kiểm soát origin nào được phép gọi API của bạn từ JavaScript. Browser gửi một request preflight OPTIONS cho các request không đơn giản; server của bạn phải phản hồi với đúng các header Access-Control-Allow-*.

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true

CORS chỉ ảnh hưởng tới browser; nó không thay thế cho authorization phía server.

Rate limiting và throttling

Bảo vệ API khỏi lạm dụng và quá tải bằng cách giới hạn số request một client có thể thực hiện trong một khoảng thời gian (token-bucket, sliding-window, v.v.). Truyền đạt giới hạn bằng các header chuẩn và trả về 429 Too Many Requests kèm Retry-After khi vượt ngưỡng:

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

Định dạng lỗi (RFC 7807 / RFC 9457)

Trả về lỗi theo một hình dạng nhất quán, đọc được bằng máy. RFC 7807 “Problem Details for HTTP APIs” (được cập nhật bởi RFC 9457) định nghĩa application/problem+json:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "quantity must be greater than 0",
  "instance": "/v1/orders",
  "errors": [
    { "field": "quantity", "message": "must be > 0" }
  ]
}

Một error contract ổn định cho phép client lập trình dựa trên lỗi thay vì phải parse văn bản mô tả.

Content negotiation

Client khai báo thứ nó có thể chấp nhận và gửi đi; server phản hồi tương ứng. Được điều khiển bằng header:

• Accept: application/json — client muốn nhận lại JSON.
• Content-Type: application/json — body của request là JSON.
• Accept-Language, Accept-Encoding — thương lượng ngôn ngữ và nén (ví dụ gzip, br).

Nếu server không thể đáp ứng header Accept thì nó trả về 406 Not Acceptable.

Real-time

Mô hình request-response của REST/GraphQL không phù hợp với nhu cầu real-time dựa trên push. Với các nhu cầu đó, hãy dùng WebSocket, SSE, GraphQL subscription, hoặc gRPC streaming — xem Real-time Communication.

So sánh: REST vs GraphQL vs gRPC vs SOAP

Tiêu chí	REST	GraphQL	gRPC	SOAP
Transport	HTTP/1.1, HTTP/2	HTTP (một endpoint)	HTTP/2	HTTP, SMTP, MQ
Định dạng payload	JSON (thường), bất kỳ	JSON	Protobuf (binary)	XML
Contract	OpenAPI (tùy chọn)	Schema (SDL, bắt buộc)	.proto (bắt buộc)	WSDL (bắt buộc)
Coupling	Lỏng	Trung bình	Chặt (stub generated)	Chặt
Streaming	Hạn chế (SSE/chunked)	Subscriptions	First-class (4 chế độ)	Không (native)
Caching	Tuyệt vời (HTTP)	Khó (client-side)	Hạn chế	Hạn chế
Thân thiện browser	Có	Có	Không (cần gRPC-Web)	Có (dài dòng)
Use case tốt nhất	Web API public/CRUD	UI hướng client, tổng hợp dữ liệu	Microservices nội bộ, latency thấp	Legacy/enterprise, WS-*
Tooling	Rất lớn, trưởng thành	Mạnh (Apollo, v.v.)	Mạnh (codegen)	Trưởng thành nhưng nặng

Best Practices

• Thiết kế contract trước. Thống nhất về OpenAPI/schema/.proto trước khi code; coi nó là source of truth và review như code.
• Dùng danh từ và ngữ nghĩa HTTP đúng chuẩn. URL hướng resource, method đúng, và status code chính xác. Không đặt verb trong REST path.
• Version hóa ngay từ đầu và chỉ break trong một major version mới; giữ các thay đổi bổ sung backward compatible.
• Luôn paginate collection; ưu tiên cursor pagination cho dataset lớn, hay thay đổi.
• Chuẩn hóa lỗi (RFC 7807/9457) và không bao giờ để lộ stack trace hay chi tiết nội bộ cho client.
• Làm cho các thao tác ghi an toàn khi retry bằng idempotency key cho POST; dùng ngữ nghĩa PUT/DELETE ở nơi phù hợp.
• Secure by default: TLS khắp nơi, authenticate mọi request, authorize theo từng resource, validate mọi input, và đặt CORS chặt chẽ.
• Rate-limit và throttle với header rõ ràng và response 429; bảo vệ các operation tốn kém.
• Giới hạn chi phí query trong GraphQL (giới hạn depth/complexity, persisted query) và giải quyết N+1 bằng DataLoader.
• Ưu tiên gRPC cho các đường service-to-service nội bộ nóng; expose REST/GraphQL ở biên (edge) cho client.
• Tài liệu hóa kèm ví dụ, generate tài liệu tương tác, và giữ tài liệu đồng bộ bằng cách generate từ contract.
• Nhất quán trên toàn bộ bề mặt API: naming, casing (chọn snake_case hoặc camelCase và giữ nguyên), định dạng ngày (ISO 8601), và hình dạng envelope.

Tài liệu tham khảo

• Roy Fielding — Architectural Styles and the Design of Network-based Software Architectures (luận án REST)
• MDN — HTTP overview and methods
• OpenAPI Specification
• GraphQL — tài liệu chính thức
• gRPC — tài liệu chính thức
• Protocol Buffers documentation
• RFC 9457 — Problem Details for HTTP APIs
• Richardson Maturity Model (Martin Fowler)

POST /v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

{ "productId": "sku_123", "quantity": 2 }

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/orders/ord_789

{ "id": "ord_789", "status": "pending", "total": 49.98 }

GET    /v1/users              # list users
POST   /v1/users              # create a user
GET    /v1/users/42           # get user 42
PUT    /v1/users/42           # replace user 42
PATCH  /v1/users/42           # partially update user 42
DELETE /v1/users/42           # delete user 42
GET    /v1/users/42/orders    # list orders belonging to user 42

{
  "id": "ord_789",
  "status": "pending",
  "total": 49.98,
  "_links": {
    "self":   { "href": "/v1/orders/ord_789" },
    "cancel": { "href": "/v1/orders/ord_789/cancel", "method": "POST" },
    "pay":    { "href": "/v1/orders/ord_789/payment", "method": "POST" }
  }
}

{
  "data": [ { "id": 41 }, { "id": 42 } ],
  "pagination": {
    "limit": 20,
    "nextCursor": "eyJpZCI6NjJ9",
    "hasMore": true
  }
}

POST /v1/payments
Idempotency-Key: 5f3a9c2e-...

{ "amount": 4998, "currency": "usd" }

GET /v1/products?category=books&limit=2 HTTP/1.1
Accept: application/json

{
  "data": [
    {
      "id": "prd_1",
      "name": "Clean Architecture",
      "price": { "amount": 3499, "currency": "usd" },
      "inStock": true
    },
    {
      "id": "prd_2",
      "name": "Designing Data-Intensive Applications",
      "price": { "amount": 5499, "currency": "usd" },
      "inStock": false
    }
  ],
  "pagination": { "limit": 2, "nextCursor": "eyJpZCI6InByZF8yIn0", "hasMore": true }
}

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
}

enum OrderStatus { PENDING PAID CANCELLED }

type Query {
  user(id: ID!): User
  users(limit: Int = 20): [User!]!
}

type Mutation {
  createOrder(userId: ID!, productId: ID!): Order!
}

type Subscription {
  orderStatusChanged(orderId: ID!): Order!
}

query GetUserWithOrders {
  user(id: "42") {
    name
    email
    orders {
      id
      total
      status
    }
  }
}

{
  "data": {
    "user": {
      "name": "Ada",
      "email": "ada@example.com",
      "orders": [
        { "id": "ord_1", "total": 49.98, "status": "PAID" }
      ]
    }
  }
}

// Without batching: 1 + N queries
// With DataLoader: 1 (users) + 1 (batched orders) queries
const orderLoader = new DataLoader(async (userIds) => {
  const rows = await db.orders.whereIn('userId', userIds);
  return userIds.map((id) => rows.filter((r) => r.userId === id));
});

syntax = "proto3";
package shop.v1;

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc WatchOrders(WatchRequest) returns (stream Order); // server streaming
}

message GetOrderRequest { string id = 1; }

message Order {
  string id = 1;
  double total = 2;
  Status status = 3;
  enum Status { PENDING = 0; PAID = 1; CANCELLED = 2; }
}

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <getOrder xmlns="http://example.com/shop">
      <id>ord_789</id>
    </getOrder>
  </soap:Body>
</soap:Envelope>

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
paths:
  /v1/orders/{id}:
    get:
      summary: Get an order by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Not found
components:
  schemas:
    Order:
      type: object
      properties:
        id:     { type: string }
        total:  { type: number, format: float }
        status: { type: string, enum: [pending, paid, cancelled] }
      required: [id, total, status]

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true

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

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "quantity must be greater than 0",
  "instance": "/v1/orders",
  "errors": [
    { "field": "quantity", "message": "must be > 0" }
  ]
}