Làm chủ thiết kế API: Chiến lược thiết yếu để phát triển API hiệu năng cao

Bài viết này là đóng góp có giá trị từ cộng đồng của chúng tôi và đã được DataCamp biên tập để rõ ràng và chính xác hơn.

Quan tâm chia sẻ chuyên môn của riêng bạn? Chúng tôi rất muốn lắng nghe! Hãy gửi bài viết hoặc ý tưởng của bạn qua Mẫu Đóng Góp Cộng Đồng.

Các bản đồ bạn thấy trong ứng dụng gọi xe và giao hàng là nhờ Google Maps API, nơi các nhà phát triển sử dụng để kích hoạt chức năng này. Google Maps API là API mặc định mà các trang web và ứng dụng dùng để hiển thị bản đồ theo thời gian thực. Nếu bạn muốn biết con số chính xác, hiện có 5.567.291 trang web đang hoạt động sử dụng API này.

Vậy vì sao Google Maps API lại thành công đến vậy? Đúng là một phần vì nó đến từ Google, nhưng còn bởi thiết kế API cho phép nhà phát triển dễ dàng tích hợp vào sản phẩm của họ.

Google Maps API chỉ là một ví dụ; có vô số API trên thị trường, như PayPal, Stripe, v.v., rất phổ biến. Thực tế, một phần thành công của các công ty này có thể nhờ vào API của họ.

Giờ đây, bất kỳ trang web hay ứng dụng nào cũng có thể mở truy cập chức năng cốt lõi của mình thông qua API. Tuy nhiên, cuối cùng việc API có được chấp nhận hay không phụ thuộc vào mức độ thiết kế tốt đến đâu. Trong blog này, chúng ta sẽ tìm hiểu những điều cơ bản về thiết kế API và các thực hành tốt nhất bạn cần tuân theo để đảm bảo các nhà phát triển yêu thích API của bạn.

Thiết kế API là gì?

Thiết kế API là quá trình xác định các phương thức và định dạng dữ liệu mà ứng dụng có thể dùng để yêu cầu và trao đổi thông tin. Nó bao gồm việc chỉ định các endpoint hoặc URL mà nhà phát triển có thể sử dụng, định dạng dữ liệu họ nên gửi và nhận, cùng hành vi mong đợi của API.

Dù đây là các khía cạnh kỹ thuật của một API, thiết kế API được quyết định bởi mục đích của API; lý do đằng sau nó. Hiểu mục đích của API sẽ làm mượt quá trình phát triển vì cung cấp cái nhìn về hành vi mong đợi, các giới hạn và khả năng phát triển trong tương lai. Thiết kế API hiện được đưa vào phạm vi rộng hơn của quản lý API để đảm bảo tính nhất quán giữa thiết kế dự kiến và API triển khai.

Nếu bạn muốn phát triển kỹ năng tích hợp và quản lý API, hãy xem khóa học của DataCamp về Làm việc với OpenAI API, giúp bạn phát triển các ứng dụng vận hành bởi AI.

Cách thiết kế một API

Mỗi API khác nhau tùy theo mục đích và chức năng mà nó đáp ứng. Tuy nhiên, có một số nguyên tắc chỉ đạo phổ quát mà mọi nhà phát triển nên tuân theo để xây dựng một API vững chắc và thân thiện với nhà phát triển. Dưới đây là cách bạn có thể thực hiện:

Bước 1: Hiểu mục đích của API

Trước khi phác thảo bản thiết kế API, hãy đảm bảo tất cả các bên liên quan đều rõ API sẽ làm gì. Làm việc chặt chẽ với lãnh đạo doanh nghiệp để làm rõ mục tiêu tổng thể. Hiểu cách API sẽ phù hợp trong bức tranh lớn hơn. Nếu có thể, hãy giao tiếp trực tiếp với người dùng cuối hoặc các nhà phát triển sẽ tương tác với API. Thu thập phản hồi về nhu cầu, điểm đau và kỳ vọng của họ để có cái nhìn về các trường hợp sử dụng thực tế của API.

Mục đích của API sẽ quyết định chức năng, tính năng, cách tài liệu hóa, các triển khai bảo mật cần có và bạn sẽ chọn đặc tả API nào.

Chọn đặc tả API phù hợp

Có nhiều đặc tả API, mỗi loại phù hợp cho một trường hợp sử dụng cụ thể. Dưới đây là một số loại phổ biến:

OpenAPI (Swagger)

OpenAPI là tiêu chuẩn được áp dụng rộng rãi để mô tả các API RESTful. Nó nổi tiếng vì sự đơn giản, cho phép dễ dàng tạo tài liệu và cung cấp cách thức chuẩn hóa để nhà phát triển hiểu và tương tác với API. OpenAPI sử dụng định dạng JSON hoặc YAML để chỉ định các endpoint của API, định dạng request và response, và phương thức xác thực. Phù hợp cho giao tiếp không trạng thái qua HTTP và là lựa chọn tốt cho API hướng đến đối tượng người dùng rộng.

GraphQL Schema

GraphQL là một lựa chọn thay thế cho API RESTful, và đặc tả của nó thường được định nghĩa bằng ngôn ngữ schema. Schema GraphQL phác thảo các kiểu dữ liệu cụ thể có thể được truy vấn và cấu trúc của các truy vấn đó. Thích hợp cho bối cảnh mà phía client cần kiểm soát chính xác dữ liệu muốn lấy.

Mở rộng kiến thức xây dựng mô hình học máy dưới dạng API bằng Flask. Khám phá hướng dẫn toàn diện của DataCamp về API Mô hình Học máy bằng Python.

RAML (RESTful API Modeling Language)

RAML là ngôn ngữ dựa trên YAML để mô tả API RESTful. Nó cung cấp cách diễn đạt dễ đọc để định nghĩa cấu trúc API, endpoint và kiểu dữ liệu. Dùng khi ưu tiên của bạn là tính dễ đọc và đơn giản.

SOAP (Simple Object Access Protocol)

SOAP là một giao thức để trao đổi thông tin có cấu trúc trong các dịch vụ web. Thường được dùng trong ứng dụng cấp doanh nghiệp với nhu cầu giao tiếp chuẩn hóa. Là lựa chọn tốt nhất khi bạn làm việc với môi trường kế thừa.

WSDL (Web Services Description Language)

WSDL thường được dùng để mô tả các dịch vụ web SOAP (Simple Object Access Protocol). Nó định nghĩa các thao tác, thông điệp và kiểu dữ liệu cho dịch vụ web, cho phép giao tiếp chuẩn hóa giữa các hệ thống khác nhau. Phù hợp nhất cho ứng dụng cấp doanh nghiệp cần hợp đồng chặt chẽ và giao tiếp chuẩn hóa.

AsyncAPI

Tương tự OpenAPI nhưng được thiết kế riêng cho API bất đồng bộ, AsyncAPI tập trung vào kiến trúc hướng thông điệp và mô tả cách các thông điệp được trao đổi giữa các thành phần khác nhau. Dùng khi không cần phản hồi theo thời gian thực từ API.

Đào sâu hơn vào phát triển API với hướng dẫn của DataCamp về Giới thiệu FastAPI. Tìm hiểu cách tạo API vững chắc bằng các framework hiện đại.

Bước 2: Xác định Endpoints và Tài nguyên

Bước tiếp theo là xác định endpoint và tài nguyên. Endpoint định nghĩa các URL (Uniform Resource Locators) hoặc URI (Uniform Resource Identifiers) cụ thể mà nhà phát triển có thể dùng để tương tác với API. Mỗi endpoint thường tương ứng với một thao tác hay hành động cụ thể. Các phương thức HTTP phổ biến như GET, POST, PUT và DELETE được dùng để thực hiện thao tác trên các endpoint này. Ví dụ:

• GET /users: Truy xuất danh sách người dùng.
• GET /users/{id}: Truy xuất chi tiết một người dùng cụ thể bằng ID.
• POST /users: Tạo người dùng mới.
• PUT /users/{id}: Cập nhật chi tiết một người dùng cụ thể.
• DELETE /users/{id}: Xóa một người dùng cụ thể.

Tài nguyên đại diện cho các thực thể hoặc đối tượng mà API của bạn quản lý. Chúng có thể là bất cứ thứ gì từ người dùng và sản phẩm đến bình luận hoặc thực thể liên quan khác trong hệ thống. Mỗi tài nguyên thường có một định danh duy nhất và gắn với một hoặc nhiều endpoint. Ví dụ:

Tài nguyên: users

Thuộc tính: ID, username, email, v.v.

Endpoints:

/users (GET - liệt kê tất cả người dùng, POST - tạo người dùng mới),

/users/{id} (GET - lấy chi tiết người dùng, PUT - cập nhật chi tiết người dùng, DELETE - xóa người dùng)

Tài nguyên: products

Thuộc tính: ID, name, description, price, v.v.

Endpoints:

/products (GET - liệt kê tất cả sản phẩm, POST - tạo sản phẩm mới),

/products/{id} (GET - lấy chi tiết sản phẩm, PUT - cập nhật chi tiết sản phẩm, DELETE - xóa sản phẩm)

Bước 3: Quyết định quy ước đặt tên

Nếu bạn muốn các nhà phát triển yêu thích API của mình, hãy đảm bảo sử dụng quy ước đặt tên rõ ràng và nhất quán. Đừng quá sáng tạo khi chọn tên cho endpoint, tài nguyên và tham số; hãy ưu tiên sự rõ ràng và đơn giản. Dưới đây là một số hướng dẫn:

1. Dùng danh từ cho tài nguyên:
• Chọn các danh từ rõ ràng, mô tả đúng cho tài nguyên. Ví dụ, /users, /products, /orders.
• Tránh các thuật ngữ mơ hồ hoặc chung chung. Hãy cụ thể để truyền tải đúng mục đích của tài nguyên.
2. Dùng động từ cho hành động:
• Dùng các phương thức HTTP (GET, POST, PUT, DELETE) để biểu đạt hành động trên tài nguyên.
• Giữ động từ nhất quán trên các endpoint. Ví dụ, dùng GET để truy xuất người dùng và POST để tạo người dùng mới.
3. Nhất quán về số ít/số nhiều:
• Quyết định tên tài nguyên ở dạng số ít hay số nhiều và nhất quán trong toàn bộ API. Ví dụ, chọn hoặc /user hoặc /users.

Bước 3: Tối ưu payload của Request và Response

Một khía cạnh quan trọng khác khi thiết kế hợp đồng API là chỉ định payload của request và response, tức dữ liệu được gửi trong yêu cầu và dữ liệu được mong đợi trong phản hồi. Việc đầu tiên bạn cần làm là chọn một định dạng dữ liệu chuẩn cho API, như JSON hoặc XML. Nên ưu tiên JSON vì được dùng rộng rãi nhờ đơn giản và dễ đọc. Bạn có thể học cách dùng JSON trong khóa Nạp dữ liệu tinh gọn với pandas của DataCamp.

Hãy giữ payload gọn nhẹ vì chúng ảnh hưởng trực tiếp đến hiệu quả của API. Bạn có thể:

1. Cố gắng triển khai nén payload (ví dụ, gzip) để giảm kích thước yêu cầu khi truyền.

2. Nếu phù hợp, hỗ trợ yêu cầu theo lô, trong đó nhiều thao tác được gộp vào một yêu cầu duy nhất.

3. Sử dụng tham số truy vấn hoặc header để thiết kế endpoint chỉ trả về dữ liệu mà client cần.

Bước 4: Triển khai Xác thực và Phân quyền

Hãy đảm bảo tính bảo mật trong thiết kế API của bạn. Có hai khía cạnh bạn cần xử lý: xác thực và phân quyền.

Về xác thực, bạn có thể triển khai OAuth và API key. API key là phương pháp đơn giản và thường dùng, trong đó một khóa duy nhất được đưa vào header của yêu cầu. Tuy nhiên, kiểu xác thực này không đủ an toàn.

Ngược lại, OAuth là một khung xác thực mạnh mẽ và linh hoạt hơn, phù hợp cho kịch bản ứng dụng bên thứ ba cần quyền truy cập. Về phân quyền, hãy xác định rõ các mức truy cập và phạm vi (scope) mà người dùng hoặc ứng dụng có thể có.

Bước 5: Áp dụng Phiên bản hóa API

Yêu cầu người dùng và công nghệ thường thay đổi theo thời gian, vì vậy API phải phát triển. Phiên bản hóa API cho phép bạn thay đổi API mà không làm gián đoạn hệ thống hiện có. Có nhiều kiểu phiên bản hóa API có thể áp dụng, như phiên bản hóa qua URL, tham số truy vấn, header, v.v.

Ví dụ,

Phiên bản hóa qua URL: https://example-api.com/v1/resource

Phiên bản hóa qua tham số truy vấn: https://example-api.com/resource?version=v1.

Bước 6: Định nghĩa thông điệp lỗi phù hợp

Lỗi là điều khó tránh khỏi trong vòng đời API. Tuy nhiên, điều quan trọng là cách xử lý lỗi. Hãy đưa vào body phản hồi các thông điệp lỗi rõ ràng, súc tích để giúp nhà phát triển hiểu vấn đề.

Bao gồm thông tin như mã lỗi, mô tả và gợi ý khắc phục. Dùng mã trạng thái HTTP tiêu chuẩn để chỉ thị thành công hay thất bại của yêu cầu (ví dụ, 200 OK cho thành công, 404 Not Found khi không tìm thấy tài nguyên, 500 Internal Server Error cho vấn đề phía máy chủ).

Bước 7: Tính đến hành vi bất ngờ

Bạn cũng nên đảm bảo API có thể xử lý các hành vi và yêu cầu bất ngờ từ người dùng cuối. Ví dụ, người dùng cuối có thể gửi nhiều yêu cầu tới cùng một tài nguyên, dẫn tới vấn đề đồng thời.

Ở chiều ngược lại, có thể phát sinh vấn đề từ phía bạn như timeout, phản hồi chậm hoặc máy chủ trả phản hồi ở định dạng không đúng với yêu cầu của client. API của bạn cần xử lý các hành động bất ngờ một cách khéo léo với thông điệp lỗi phù hợp.

Bước 8: Tài liệu hóa

Khi bạn đã làm mọi thứ, phần cuối cùng là tài liệu. Tài liệu giống như cẩm nang hướng dẫn các nhà phát triển khác cách API của bạn hoạt động. Đây là một trong những yếu tố then chốt ảnh hưởng đến việc chấp nhận và sử dụng API. Do đó, hãy đảm bảo tài liệu rõ ràng, súc tích và dễ hiểu. Một số thực hành tốt:

• Tránh thuật ngữ kỹ thuật không cần thiết có thể gây rối cho nhà phát triển.
• Tổ chức tài liệu theo cấu trúc logic và phân cấp. Dùng mục, tiểu mục và tiêu đề để giúp người dùng nhanh chóng tìm thông tin cần thiết.
• Bao gồm ví dụ tương tác hoặc sandbox API để nhà phát triển thử nghiệm trực tiếp từ tài liệu.
• Cân nhắc dùng công cụ như Swagger hoặc OpenAPI để tạo tài liệu API tương tác.

Thiết kế API trước hay viết mã trước

Khi xây dựng API, có hai cách tiếp cận bạn có thể theo: thiết kế API trước hoặc viết mã trước.

Chiến lược vừa bàn đến là cách tiếp cận thiết kế API trước, trong đó định nghĩa đặc tả của API, bao gồm endpoint, định dạng dữ liệu, cơ chế xác thực và kiến trúc tổng thể, trước khi viết mã hiện thực các đặc tả đó. Mục tiêu là thiết lập một thiết kế API rõ ràng, thấu đáo, đáp ứng yêu cầu hệ thống và dễ để nhà phát triển hiểu, sử dụng.

Còn viết mã API trước tập trung vào việc viết mã trước khi định nghĩa đặc tả hay tài liệu. Như vậy, nhà phát triển điều chỉnh API dựa trên trải nghiệm triển khai và phản hồi từ thử nghiệm, và thiết kế tiến hóa khi mã được viết.

Cách tiếp cận nào tốt hơn?

Có thể nói cách viết mã trước mang lại linh hoạt và tốc độ trong phát triển vì cho phép tạo mẫu nhanh. Tuy nhiên, cũng có nhiều thách thức. Không có đặc tả rõ ràng ngay từ đầu có thể dẫn đến rủi ro hiểu nhầm hoặc thiếu nhất quán trong cách các phần của API được triển khai. Cuối cùng, điều này phụ thuộc vào yêu cầu của dự án và sở thích của đội ngũ phát triển.

Khám phá khả năng sáng tạo của API với hướng dẫn của DataCamp về DALL-E 3 API để hiểu cách tận dụng AI cho các giải pháp đổi mới.

Lời kết

Có nhiều khía cạnh kỹ thuật trong thiết kế API. Tuy nhiên, bạn nên coi API như một sản phẩm được tạo ra để giải quyết điểm đau của người dùng cuối. Khi thiết kế API được dẫn dắt bởi các điểm đau đó, khả năng được chấp nhận nhanh sẽ cao hơn.

Nâng cao kỹ thuật nạp dữ liệu bằng API với khóa học của DataCamp, Nạp dữ liệu tinh gọn với pandas. Trải nghiệm thực hành xử lý dữ liệu hiệu quả.