<aside> ©️ IT: Từ A tới Á cho người ngoài ngành by @Rose Trinh

</aside>

Như trong bài trước mình đã tìm hiểu về API, công cụ kết nối các hệ thống và ứng dụng khác nhau. API giúp các ứng dụng khác nhau "nói chuyện" với nhau, cho phép chúng chia sẻ dữ liệu và chức năng một cách hiệu quả.

Để API hoạt động hiệu quả và giúp các bên kết nối dễ dàng, một tài liệu hướng dẫn sử dụng API là cực kỳ quan trọng. Tài liệu này sẽ hướng dẫn các nhà phát triển và người dùng cách kết nối và sử dụng API một cách chính xác.

Nếu bạn nghe khách hàng yêu cầu API 설명서, API 명세서, hoặc Swagger, thì có nghĩa là họ đang yêu cầu một tài liệu giới thiệu về cách sử dụng API. Tài liệu này có thể được soạn thảo dưới dạng tài liệu truyền thống trên Word, Excel, hoặc trên các nền tảng như Confluence, Wiki, hoặc thậm chí trên trang web của công ty. Ví dụ, Momo, Notion vv. có cung cấp hướng dẫn API trên trang web của họ cho các đối tác bên ngoài muốn tích hợp tính năng vào ứng dụng của mình.

Introduction

Cấu Trúc của API Document

Dưới đây là cấu trúc cơ bản của một API Document, mà các bạn có thể gặp, và mình sẽ đưa thí dụ của API /pages của Notion ra để giải thích các mục nha.

1. Giới thiệu API Endpoint:

   • URL: Địa chỉ của endpoint.
   • Phương Thức HTTP: GET, POST, PUT, DELETE, v.v.
   • Mô Tả: Tóm tắt về chức năng của endpoint.

2. Xác Thực và Phân Quyền

   • Phương Thức Xác Thực: Mô tả các phương thức xác thực (API Key, OAuth, JWT, v.v.).
   • Cấp Quyền: Các quyền cần thiết để truy cập các API endpoints.

3. Chi Tiết Endpoint:

   • Tham Số (Parameters): Các tham số cần thiết và tùy chọn cho điểm cuối, bao gồm mô tả và kiểu dữ liệu.
   • Ví Dụ Yêu Cầu (Request): Ví dụ về cách gửi yêu cầu đến điểm cuối.
   • Ví Dụ Phản Hồi (Response): Ví dụ về phản hồi từ điểm cuối, bao gồm mã trạng thái và định dạng dữ liệu trả về.
   • Lỗi (Error Codes): Mã lỗi có thể xảy ra và cách xử lý chúng.

Thông Tin Bổ Sung

• Hướng Dẫn Sử Dụng: Các bước hướng dẫn cơ bản về cách sử dụng API.
• Chỉ Dẫn Bảo Mật: Các biện pháp bảo mật cần thiết khi sử dụng API.
• Thực Hành Tốt Nhất: Các thực hành tốt nhất và mẹo để sử dụng API hiệu quả.
• Tài Liệu Tham Khảo: Các liên kết đến tài liệu bổ sung và hướng dẫn.
• Hỗ Trợ và Liên Hệ: Thông tin liên hệ để được hỗ trợ và giải đáp thắc mắc.

Changelog

• Phiên Bản: Thông tin về các phiên bản của API và các thay đổi qua các phiên bản.
• Cập Nhật: Chi tiết về các cập nhật mới, sửa lỗi và cải tiến.

https://developers.notion.com/reference/post-page

#1. Giới thiệu API /pages sử dụng cho việc tạo một page trên Notion

#2. Xác thực và Phân Quyền Notion yêu cầu phải có Notion API Key, để có thông tin đó thì làm theo hướng dẫn ở phần Requirements.

#3. Chi Tiết Endpoint:

#4. Thông Tin Bổ Sung

Swagger

Tự viết API Document được thì cần gì tool? Swagger giúp đơn giản hóa việc tạo tài liệu API, làm cho nó dễ dàng hơn để duy trì, sử dụng, và phát triển API. Một số framework và thư viện còn hỗ trợ sinh ra tệp Swagger từ mã nguồn của ứng dụng, như Spring Boot với Springfox hoặc Django với drf-yasg. Những công cụ này tự động sinh ra tài liệu Swagger từ các chú thích hoặc cấu hình trong mã nguồn làm việc viết tài liệu (công việc “yêu thích” của các developer được dễ dàng hơn).

Như với cá nhân mình thì mình thích Swagger vì cung cấp giao diện người dùng (Swagger UI) cho phép thử nghiệm các endpoint của API trực tiếp từ trình duyệt, giúp kiểm tra và xác minh chức năng API cả lúc mà team FE chưa làm xong màn hình và mình muốn kiểm thử xem API BE có chạy hay chưa.

https://www.youtube.com/watch?v=7MS1Z_1c5CU

Đọc thêm

API là gì?

Webhook và API Polling

<aside> 📥 Mọi feedback xin gửi về: https://www.linkedin.com/in/rose-trinh/

</aside>