10 Thành phần quan trọng của Tài liệu API
Nhiều tổ chức đang tận dụng sức mạnh của API để tối ưu hóa hoạt động kinh doanh của họ. API đã trở thành một cách để mở khóa giá trị và cung cấp dịch vụ bổ sung.
Bất chấp sự phổ biến chung của chúng, không phải API nào cũng thành công. Việc áp dụng và sử dụng API phần lớn quyết định thành công của nó. Để tăng cường áp dụng, API của bạn cần phải dễ tìm và dễ sử dụng.
Cách tốt nhất để làm điều này là ghi lại chi tiết API của bạn. Điều này bao gồm chi tiết các thành phần quan trọng để làm cho chúng dễ hiểu hơn. Tìm hiểu một số thành phần mà bạn nên đưa vào tài liệu API của mình.
Mục Lục
Tài liệu API là gì?
Tài liệu API là nội dung kỹ thuật mô tả chi tiết về API. Đó là sổ tay chứa tất cả thông tin cần thiết để làm việc với API. Tài liệu bao gồm vòng đời API và hướng dẫn tích hợp và sử dụng các thành phần của nó.
Tài liệu API bao gồm các mô tả tài nguyên, điểm cuối, phương thức, yêu cầu và ví dụ về phản hồi. Nó cũng có thể bao gồm các hướng dẫn và hướng dẫn thực tế chỉ cho người dùng cách tích hợp nó. Khám phá từng phần giúp người dùng hiểu rõ về cách tích hợp và sử dụng API.
Các trình chỉnh sửa như Google Tài liệu đã từng được sử dụng rộng rãi cho tài liệu API chuyên nghiệp. Ngày nay, có nhiều công cụ tiên tiến hơn như Document 360, Confluence và GitHub Pages. Những công cụ này giúp tích hợp văn bản và mã cho quy trình làm việc dễ dàng hơn.
1. Tổng quan và Mục đích của API
Bước đầu tiên trong việc ghi lại một API là cho người dùng biết nó nói về cái gì. Bao gồm thông tin về loại tài nguyên mà nó cung cấp. Các API thường có nhiều tài nguyên khác nhau mà chúng trả về, vì vậy người dùng có thể yêu cầu những gì họ cần.
Mô tả ngắn gọn, thường là một đến ba câu mô tả tài nguyên. Mô tả tài nguyên có sẵn, các điểm cuối và các phương thức được đính kèm với từng điểm cuối. Là nhà phát triển API, bạn mô tả tốt nhất các thành phần, chức năng và trường hợp sử dụng của nó.
Đây là một ví dụ về mô tả của API Airbnb:
2. Phương thức xác thực và ủy quyền
API xử lý hàng nghìn yêu cầu và lượng dữ liệu khổng lồ. Xác thực là một trong những cách để đảm bảo dữ liệu API của bạn và người dùng được an toàn khỏi tin tặc. Xác thực API xác minh danh tính của người dùng và cấp cho họ quyền truy cập vào tài nguyên.
Có một số cách để đảm bảo an ninh điểm cuối. Hầu hết các API đều sử dụng khóa API. Đây là một chuỗi ký tự mà người dùng có thể tạo từ trang web và sử dụng để xác thực.
Tài liệu API sẽ hướng dẫn người dùng cách xác thực và ủy quyền danh tính của họ. Sơ đồ sau đây hiển thị thông tin xác thực Twitter API.
3. Điểm cuối, Mẫu URI và Phương thức HTTP
Trong phần này, trình bày cách truy cập tài nguyên. Các điểm cuối chỉ hiển thị phần cuối của đường dẫn, do đó có tên như vậy. Chúng hiển thị quyền truy cập vào tài nguyên và các phương thức HTTP mà điểm cuối tương tác với, cụ thể là GET, POST hoặc DELETE.
Một tài nguyên có thể có nhiều điểm cuối. Mỗi người có một con đường và phương pháp khác nhau. Điểm cuối thường có mô tả ngắn gọn về mục đích của chúng và mẫu URL.
Mẫu mã sau đây hiển thị điểm cuối NHẬN người dùng trên Instagram.
GET /me?fields={fields}&access_token={access-token}
4. Định dạng yêu cầu và phản hồi
Bạn phải ghi lại các định dạng yêu cầu và phản hồi để người dùng biết điều gì sẽ xảy ra. Yêu cầu là một URL từ máy khách yêu cầu tài nguyên, trong khi phản hồi là phản hồi từ máy chủ.
Sau đây là một yêu cầu mẫu mà bạn có thể gửi tới API LinkedIn.
GET https://api.linkedin.com/v2/{service}/1234
Và đây là một phản hồi mẫu mà nó có thể trả về:
{
"id": 1234,
"relatedEntity": "urn:li:relatedEntity:6789"
}
5. Tham số và Tiêu đề
Bạn cũng nên ghi lại các tham số của điểm cuối, đây là các tùy chọn mà bạn có thể chuyển cho chúng. Tham số có thể là ID hoặc số chỉ định số lượng hoặc loại dữ liệu được trả về trong phản hồi.
Có nhiều loại tham số khác nhau, bao gồm tham số tiêu đề, đường dẫn và chuỗi truy vấn. Các điểm cuối có thể chứa các loại tham số khác nhau.
Bạn có thể bao gồm một số tham số làm tiêu đề yêu cầu HTTP. Thông thường, chúng dành cho mục đích xác thực như khóa API. Dưới đây là ví dụ về tiêu đề có khóa API:
headers: {
'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}
Bạn bao gồm các tham số đường dẫn trong phần nội dung của điểm cuối ngay trên URL. Chúng chỉ cho người dùng cách thức và vị trí đặt các tham số cũng như cách phản hồi sẽ xuất hiện. Các từ trong dấu ngoặc nhọn là tham số.
Bạn cũng có thể sử dụng dấu hai chấm hoặc cú pháp khác để biểu thị các tham số đường dẫn.
/service/myresource/user/{user}/bicycles/{bicycleId}
Với tham số truy vấn, bạn phải đặt dấu chấm hỏi (?) trước truy vấn trên điểm cuối. Tách từng tham số sau đó bằng dấu và (&). Microsoft có tài liệu tốt về API Đồ thị.
6. Mã lỗi và Xử lý lỗi
Đôi khi các yêu cầu HTTP không thành công, điều này có thể khiến người dùng bối rối. Bao gồm các mã lỗi dự kiến trong tài liệu để giúp người dùng hiểu các lỗi.
LinkedIn cung cấp mã lỗi HTTP tiêu chuẩn để xử lý lỗi:
7. Đoạn mã mẫu
Các đoạn mã là những phần thiết yếu trong tài liệu của bạn. Họ chỉ cho người dùng cách tích hợp API bằng nhiều ngôn ngữ và định dạng khác nhau. Bao gồm cách cài đặt và tích hợp SDK (bộ công cụ phát triển phần mềm) bằng nhiều ngôn ngữ khác nhau trong tài liệu.
RapidAPI có các ví dụ hay về đoạn mã dành cho nhà phát triển:
9. Phiên bản API và nhật ký thay đổi
Phiên bản API là một phần thiết yếu của thiết kế API. Nó đảm bảo việc cung cấp các dịch vụ không bị gián đoạn cho người dùng của bạn. Lập phiên bản có thể nâng cao API bằng các phiên bản mới mà không ảnh hưởng đến ứng dụng khách.
Người dùng có thể tiếp tục sử dụng các phiên bản cũ hơn hoặc chuyển sang các phiên bản nâng cao kịp thời. Nếu có những thay đổi mới đối với nhật ký, hãy đưa chúng vào tài liệu để người dùng biết.
Microsoft Graph API có nhật ký thay đổi được ghi lại đầy đủ:
Cuối cùng, bao gồm các liên hệ quan trọng trong tài liệu để được hỗ trợ và phản hồi. Những điều này đảm bảo rằng người dùng có thể liên hệ với bạn bằng các báo cáo lỗi và thông tin về cách cải thiện API.
Giá trị của tài liệu API
Nếu bạn xây dựng một API cho giá trị thương mại, mức tiêu thụ sẽ quyết định sự thành công của nó. Và để người dùng sử dụng API của bạn, họ phải hiểu nó.
Tài liệu đưa API vào cuộc sống. Nó giải thích các thành phần một cách chi tiết bằng ngôn ngữ đơn giản bán giá trị và cách sử dụng của nó cho người dùng. Người dùng sẽ vui vẻ sử dụng API của bạn nếu họ có trải nghiệm nhà phát triển tuyệt vời.
Tài liệu tốt cũng giúp đơn giản hóa việc bảo trì và mở rộng API. Các nhóm làm việc với API có thể sử dụng tài liệu để quản lý nó.