Thiết kế API
Spec OpenAPI là hợp đồng giữa app và server, và mọi request đều được kiểm tra theo nó.
API HTTP đi theo hướng OpenAPI first. Thiết kế một tính năng bắt đầu từ server/api/openapi.yaml và các file nó tham chiếu trong paths/, schemas/, parameters/ và responses/. Code viết ra để khớp với spec, chứ spec không chạy theo code.
Spec ràng buộc code thế nào
Server nhúng spec vào binary và nạp nó lúc khởi động, nên binary luôn mang theo đúng hợp đồng mà nó dùng để kiểm tra. Trước khi handler chạy, một middleware validate request theo operation tương ứng: tham số path và query, header và body JSON. Luật về hình dạng dữ liệu (trường bắt buộc, độ dài, format, enum) chỉ nằm trong spec và handler không lặp lại, còn luật nghiệp vụ nằm trong các module.
Bộ test giữ cho hai bên luôn khớp nhau:
- spec nạp và validate được, kể cả các tham chiếu;
- tập route đã đăng ký và tập operation trong spec phải trùng nhau, operation thiếu route hay route thiếu operation đều làm test fail;
- client e2e validate mọi response theo operation nó gọi;
- mỗi status code mà operation khai báo phải xuất hiện trong ít nhất một test e2e.
Quy ước
- Mọi route bắt đầu bằng
/v1. Khi có thay đổi phá vỡ tương thích thì thêm/v2song song, vì app đã cài có thể ở bản cũ hàng tháng trời. - JSON dùng
snake_case, trường lạ bị từ chối, body tối đa 1 MB. - ID là UUIDv7.
/healthzvà/readyznằm ngoài/v1, báo process còn sống và đã sẵn sàng.
Đọc và thử API
Playground hiện toàn bộ spec và gửi request tới production, dev hoặc stack local. Bản thân server không phục vụ trang docs nào. Server local chạy ở http://localhost:8080; cách dựng xem ở Môi trường local.
Phần lớn màn hình của app được đọc bằng một lần gọi cho mỗi view, qua các endpoint mô tả ở Screens.