(Including English version)
Việc viết một tài liệu hướng dẫn thiết kế REST API khá nhàm chán không ? Có ai quan tâm để đọc đâu ? và liệu nó có đáng không ?
Những câu hỏi này nhắc mình nhớ đến câu chuyện sau: trong một dự án của công ty nọ, có nhóm lập trình viên (một tech lead và 2 bạn lập trình viên) chịu trách nhiệm viết REST API cho ứng dụng.
Sau khi phân tích yêu cầu, phân chia nhiệm vụ cho mỗi thành viên viết các chức năng và bắt tay thiết kế và cài đặt các api. Mỗi người cũng thống nhất viết theo nguyên tắc REST API (chỉ trao đổi miệng).
Trong quá trình cài đặt, lập trình viên A đặt tên resource là GET /users, POST /property-legals, sử dụng mã lỗi như 400,409.., trong khi lập trình viên B đặt tên là GET /user, POST /property_legal, không trả về mã lỗi mà chỉ ghi nội dung lỗi như “Mã không hợp lệ” ..
Đến khi anh tech lead xem lại thì thấy rằng mỗi lập trình viên làm các cách khác nhau. Thế là triệu tập một vài cuộc họp để trao đổi và thống nhất cách đặt tên, cách trả về như thế nào. Cứ mỗi đợt xem lại, anh tech lead lại gọi họp lại để thêm quy tắc cho vấn đề bảo mật hoặc đối tượng trả về etc. Chính vì vậy, gây mất thời gian cho các thành viên phải cập nhật, sửa lại và tinh thần không thoải mái.
Cũng có nhiều lý do khác nhau mà tài liệu này mọi người không quan tâm ví dụ:
- Thông thường khách hàng sẽ cung cấp tài liệu REST API để cho lập trình viên sử dụng
- Công ty không có bộ hướng dẫn thiết kế REST API có sẵn
- Lập trình viên nghĩ chỉ có mình làm trên dự án ..
Vì vậy, nếu ko có tài liệu hướng dẫn thiết kế REST API thì sẽ gây những khó khăn như sau:
- Khó bảo trì mã nguồn: mỗi lập trình sẽ viết những cách khác nhau vì vậy không có sự thống nhất giữa cách đặt tên uri, resources, status codes ..
- Mất thời gian để trao đổi và sửa..
Chính vì thế, việc có tài liệu hướng dẫn thiết kế REST API sẽ giúp:
- Việc thiết kế và xem duyệt REST API sẽ đơn giản hơn
- Bảo đảm sư nhất quán những API
- Ít tranh luận hơn
Lưu ý rằng tài liệu hướng dẫn thiết kế REST API cũng nên đơn giản và dễ hiểu cho tất cả mọi người. Như vậy, tùy thuộc vào doanh nghiệp hoặc tính chất sản phẩm mà công ty sẽ định nghĩa những quy tắc cho phù hợp.
Thường trong tài liệu hướng dẫn thiết kế REST API, nó bao gồm những thông tin chính sau:
- Quy trình thiết kế REST API
- Quy ước đặt tên cho Resource: mình đề nghị sử dụng tiếng anh để đặt tên vì tiếng việt không dấu có nhiều ý nghĩa sẽ gây nhầm lẫn
- ví dụ tên resource là users, nếu dịch sang tiếng việt là người dùng và ghi không dấu nguoi_dung, nguoidung
- Phương thức HTTP (PUT, POST, GET, PATCH): Khi nào thì dùng những phương thức này ..
- Mã trạng thái HTTP / HTTP Status codes: có trên 70 mã trạng thái HTTP nhưng mình nghĩ chỉ sử dụng vài nhóm với vài mã trạng thái thôi
- Ví dụ: nhóm mã thành công 2xx: sử dụng 2 mã 200 và 201 (created)
- Nhóm mã 3xx, 4xx, 5xx (500)
- Quy ước đặt phiên bản cho API /API Versioning: cái này cũng cần thiết, có nhiều cách đặt phiên bản ví dụ: major.minor.patch or v1, v2.. Tùy theo nhu cầu thì sử dụng cách đặt phiên bản cho phù hợp. Mình thì thích cách dùng v1,..
- Quy ước cho tìm kiếm, lọc và sắp xếp (Search, filtering, sorting)
- Xử lý lỗi / Error handling
- Bảo mật / Security
- …
Đối với những công ty lớn như google, facebook, microsoft, github, amazon etc họ đều phải có tài liệu này để giúp các nhóm lập trình viên làm việc chung với nhau.
Mặc dù công việc viết hướng dẫn này rất chán nhưng nó sẽ tiết kiệm cho chúng ta nhiều thời gian và tiền bạc.
// English version
Why are API design guidelines important?
Writing API design guidelines is boring? Does anyone care to read? And is it worth it ?
These questions remind me of the following story: in a project of a certain company, there was a group of programmers including a tech lead and 2 programmers are responsible for writing a REST API for the application.
After analyzing the requirements, assigning each member to write the functions and start designing and implementing the api. Each person also agreed to comply with the principle of REST API (only oral communication).
During the programming, programmer A named the resource GET /users, POST /property-legals, using an error code like 400,409.., while programmer B named it GET /user, POST /property_legal, doesn’t return error code but just write error content like “Invalid code” ..
When the tech lead reviewed, he saw that each programmer did it differently. So he called a few meetings to discuss and agree on how to name and set error codes. Every review, the tech lead calls a meeting to add rules for security or return objects etc. Therefore, it takes time for members to update, correct and feel uncomfortable.
There are also many different reasons that people are not interested in this document, for example:
- Usually the client will provide API specification documentation for the programmer to use
- The company does not have available API design guidelines
- The programmer thinks he works solo on the project..
Therefore, if there is no API design guidelines, it will cause the following difficulties:
- Difficult to maintain source code: each programmer will program them differently so there is no consistency about naming uri, resources, status codes..
- Takes time to discuss and fix …
Therefore, API design guidelines will help:
- Simpler API design and review
- Ensuring API Consistency
- Less discussion
Note that the API design guidelines should also be simple and understandable for everyone. Thus, depending on the business or the organization, the company will define the rules accordingly. But often in API design guidelines, it covers the following main information:
- REST API Design workflow
- Resource naming: I suggest using English for naming because unsigned Vietnamese has many meanings that will cause confusion.
- For example, the resource name is users, in English: users, but in Vietnamese: nguoi_dung, nguoidung etc.
- HTTP methods (PUT, POST, GET, PATCH): When & How should we use these operations ?
- HTTP Status codes: there are more than 70 HTTP status codes but I think only use a few groups with a few status codes:
- Example: 2xx success code: use 2 codes such as 200 (success) and 201 (created)
- Code group 3xx, 4xx, 5xx (500)
- API Versioning: this is also necessary, there are many ways to set the version for example:
- Method 1: major.minor.patch
- Method 2: v1, v2…
- Depending on your needs, use the appropriate version. I like using v1,..
- Searching, filtering and sorting
- Error handling
- Security
- ….
For big companies like google, facebook, microsoft, github, amazon etc, they all must have this document to help their teams work together.
In conclusion, although writing these guidelines are boring, it will save us a lot of time and money.
