RESTful API design: những quyết định quan trọng trước khi viết code

API là contract giữa backend và tất cả clients. Một khi public, thay đổi breaking là cực kỳ tốn kém. Đầu tư thời gian vào design trước khi implement tiết kiệm nhiều lần effort về sau.

Resource naming và HTTP verbs

Resources là nouns, không phải verbs: /users, /orders, không phải /getUsers, /createOrder. HTTP verbs mang ý nghĩa ngữ nghĩa: GET (read), POST (create), PUT (replace), PATCH (partial update), DELETE. Dùng đúng verbs giúp clients predict behavior.

Nested resources cho relationships: /users/{id}/orders nhưng chỉ nếu order không thể tồn tại độc lập. Tránh nest quá 2 levels — thay vào đó dùng filter: /orders?userId={id}.

Error Responses nhất quán

Định nghĩa error response schema từ đầu và stick with it. Minimum: status code, error code (machine-readable), message (human-readable), và request ID để trace. RFC 9457 (Problem Details for HTTP APIs) là standard tốt để follow.

Đừng trả 200 OK với error body — đây là anti-pattern gây đau đầu cho client developers. HTTP status codes đã được thiết kế có nghĩa: dùng chúng đúng mục đích.

Pagination

Offset pagination (?page=2&limit=20) đơn giản nhưng có vấn đề với large datasets (slow COUNT query) và dữ liệu thay đổi trong khi paginate. Cursor pagination (stable, efficient) là lựa chọn tốt hơn cho feeds và real-time data.

Versioning Strategy

Ba approach phổ biến: URL versioning (/v1/users), header versioning (Accept: application/vnd.api+json;version=1), và query parameter (?version=1). URL versioning rõ ràng nhất và dễ test nhất — được khuyến nghị cho public APIs.

Authentication và Authorization

JWT cho stateless authentication, nhưng cẩn thận với token size và refresh strategy. API keys cho server-to-server, với rate limiting theo key. OAuth 2.0 khi cần third-party authorization. Đừng bao giờ truyền credentials qua URL query parameters — chúng xuất hiện trong logs.