9. Thiết kế document và version cho API

Image for post
Image for post

Thiết kế document.

Đây là vấn đề rất quan trọng. Việc thiết kế một hệ thống tốt phải đi kèm với một tài liệu rõ ràng và dễ hiểu.

Trong quá trình phát triển chắc hẳn ai cũng đã từngtích hợp 1 vài API từ các hệ thống khác như của Facebook, Google, Twitter… có lẽ nó quá dễ dàng để bắt đầu, với những hệ thống như vậy thì rất hiếm khi ta gặp khó chịu khi đọc hiểu các API của họ.

Gần đây mình có tích hợp API của 2 bên giao hàng là GHTK và Ahamove.

Đây là vấn đề. Đối với ghtk thì cũng khá oke, tài liệu khá rõ ràng, đầy đủ, đẹp đẽ, support cũng tốt, quy trình cũng tạm ổn, chỉ có điều ship nội thành Hà Nội và TP.HCM thì mặc định giá tiền luôn, nên khỏi tính toán nhiều, tiết kiệm thiệt 😁.

Sang đến Ahamove thì muốn đập máy luôn. Tài liệu thì lôm côm, tham số ghi lúc thừa lúc thiếu, nhiều chỗ còn ko biết tham số có bắt buộc hay là không, chỉ có test thử mới biết, các dịch vụ thì phải hỏi mới biết, chứ trên tài liệu ko thấy ghi gì, lúc test thì đều phải gọi điện để xin test, ko tự động. Các API thì gửi json lên url hết, tất cả CURD thì đều phương thức GET hết. Có mỗi cái callback thì bằng POST, nhưng cái này là gọi sang hệ thống bên mình 😫 Support thì ko đến nơi, trạng thái đơn hàng thì ko mô tả riêng, đến khi lên production thì còn khá nhiều vấn đề…, được mỗi điểm cộng là viết tài liệu bằng…tiếng anh 😞

Đấy thế mới biết, hệ thống có cao siêu đến đâu thì đến, cái tài liệu không rõ ràng đã cản trở rất nhiều rồi, mình thì code hay bug, nên hay chửi thề những lúc này lắm 😁

Lan man quá, quay lại vấn đề chính, nay giới thiệu một số công cụ tạo tài liệu API mà mình thấy ổn nhất.

Đứng số 1 là Slate, cái này mình thấy oke nhất, cũng là cái mà bên ghtk họ triển khai. Các bạn hoàn toàn có thể sử dụng google doc nếu ít API hoặc ko public chẳng hạn.

Cái thứ 2 là Flatdoc, cái này cũng gần tương tự cái trên, tùy vào phong cách và mỗi hệ thống mà chọn.

Ai thích màu mè thì chọn cái Swagger này, về cơ bản thì nên viết tài liệu trên 1 template đơn giản nhất, miễn sao thể hiện được sự rõ ràng là được.

Mọi người có thể tham khảo thêm các API document ở các hệ thống lớn để học hỏi, mình giới thiệu API của Spotify, khá đẹp và quan trọng là rất chi tiết.

Xem thêm cấu trúc viết ở đây.

Okay, mong là hệ thống các bạn viết ko để cho ai phải ….chửi thề 😁

Vấn đề version.

Một điều chắc chắn là, hệ thống của bạn sẽ có rất nhiều sự thay đổi, nhất là nó phát triển và mở rộng.

Vậy nên chuẩn bị trước không thừa. Có khá nhiều cách để phân biệt, cách đơn giản nhất là triển khai nó trên route luôn (có thể dùng param để phân biệt).

Ví dụ:

'prefix'     => 'api/v1'

Một điểm lưu ý nữa là: mỗi sự thay đổi trên API sẽ đều được cập nhật đồng thời trên changelog của document. Sợ nhất là đến khi test bị lỗi xong họ chốt một câu xanh dờn: “ơ, mình quên chưa cập nhật tài liệu” 😫

Okay, see you next, have a nice weekend 😀

Written by

Be Curious!| ☕️+✍🏼=❤️ | buihuycuong.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store