API là gì? Hướng dẫn thực tiễn về giao diện phần mềm

API thu thập dữ liệu không có sự xâm phạm cung cấp các giao diện cụ thể cho nhiệm vụ trả về dữ liệu web công khai có cấu trúc cho quy trình làm việc ứng dụng.

API có nghĩa là Giao diện lập trình ứng dụng

Giao diện lập trình ứng dụng là một bộ quy tắc và khả năng được phơi bày mà phần mềm có thể gọi hoặc tiêu thụ. Giao diện này ẩn chi tiết triển khai phía sau một ranh giới ổn định. Người gọi cần biết hoạt động nào tồn tại, đầu vào mà nó chấp nhận, đầu ra hoặc hiệu ứng mà nó tạo ra, và cách lỗi được báo cáo. Nhà cung cấp có thể thay đổi mã bên trong trong khi vẫn bảo tồn hợp đồng đó, cho phép cả hai bên phát triển với ít sự phối hợp hơn.

Các API đã tồn tại trước web và rộng hơn các điểm cuối HTTP. Một thư viện ngôn ngữ lập trình phơi bày các chức năng, lớp và kiểu. Hệ điều hành phơi bày các cuộc gọi hệ thống. Một trình điều khiển thiết bị phơi bày các hoạt động cho hệ điều hành. Một dịch vụ từ xa phơi bày các tin nhắn qua mạng. Bảng thuật ngữ API NIST miêu tả một API như một điểm truy cập hoặc chức năng thư viện được xác định rõ, trong khi định nghĩa tập trung vào web của MDN đề cập đến các tính năng và quy tắc mã có sẵn cho các ứng dụng.

Cách gọi API Web hoạt động

API là gì dễ hoạt động hơn khi đường dẫn xử lý của nó rõ ràng. Các giai đoạn sau đây cho thấy nơi có thể thu thập bằng chứng và nơi chính sách có thể thay đổi kết quả.

Khám phá và hợp đồng

Người tiêu dùng đọc tài liệu hoặc mô tả có thể đọc được bởi máy để biết địa chỉ cơ bản, hoạt động, tham số, đại diện, phương thức xác thực, giới hạn và mô hình lỗi. Một hợp đồng có thể là tài liệu không chính thức hoặc một sơ đồ chính thức hỗ trợ việc xác thực và tạo công cụ.

Xử lý yêu cầu

Khách hàng xây dựng một yêu cầu, xác định bản thân khi cần thiết, và gửi đầu vào ở vị trí được xác định bởi giao diện. Một cổng hoặc dịch vụ xác thực người gọi, ủy quyền hoạt động, xác thực đầu vào, áp dụng chính sách, gọi logic ứng dụng và tạo ra một phản hồi.

Giải thích phản hồi

Khách hàng đánh giá trạng thái vận chuyển, lỗi ứng dụng, siêu dữ liệu và đại diện được trả về. Sau đó, nó ánh xạ kết quả vào các loại cục bộ hoặc hành vi hiển thị cho người dùng. Các khách hàng chính xác không giả định rằng một phản hồi hợp lệ về mặt cú pháp có nghĩa là hoạt động kinh doanh được yêu cầu thành công.

Các phần của hợp đồng API

Từ vựng xung quanh API là gì trải rộng từ kiến trúc, dữ liệu và hoạt động. Bảng giữ những trách nhiệm đó tách biệt để một cuộc đánh giá thiết kế có thể đặt ra câu hỏi đúng.

Những gì API cho phép

Một trường hợp thực tế cho 'What Is an API' bắt đầu từ công việc mà hệ thống phải thực hiện. Những ví dụ này cho thấy yêu cầu đó thay đổi giao diện hoặc quyết định mạng như thế nào.

Cách đánh giá một API trước khi tích hợp

Bắt đầu với sự phù hợp. Xác nhận rằng API công khai hoạt động và dữ liệu cần thiết cho quy trình làm việc thực tế, bao gồm lọc, phân trang, thứ tự, độ mới và hành vi khu vực. Kiểm tra xem cách đại diện có chứa các định danh ổn định hay không và liệu các trường vắng mặt có bị bỏ qua hay được trả về dưới dạng null hay không. Một ví dụ trau chuốt không thay thế một hợp đồng hoàn chỉnh.

Kiểm tra các quy tắc hoạt động. Xác thực và cấp quyền xác định ai có thể gọi cái gì. Các giới hạn và điều kiện tải xác định hình dạng công việc khả thi. Chính sách phiên bản và mất hỗ trợ xác định rủi ro bảo trì. Tài liệu lỗi nên phân tách lỗi của người gọi, lỗi truy cập, điều kiện quota và lỗi của nhà cung cấp để khách hàng có thể thực hiện hành động an toàn và giới hạn.

Xem xét bảo mật như một phần của giao diện. The HTTP semantics specification xác định các phương thức yêu cầu, khái niệm trạng thái và siêu dữ liệu đại diện được nhiều API web sử dụng. Mã hóa vận chuyển bảo vệ dữ liệu đang di chuyển, nhưng ứng dụng vẫn cần thông tin xác thực có đặc quyền tối thiểu, xác thực đầu vào, lưu trữ bí mật, hồ sơ kiểm toán và kiểm soát để không tiết lộ các trường nhạy cảm.

Những sai lầm trong tích hợp API cần tránh

• Đối xử với các ví dụ như là toàn bộ sơ đồ. Các ví dụ có thể bỏ qua các trường tùy chọn, có thể null, phân trang hoặc lỗi mà lưu lượng sản xuất sẽ chứa.
• Nhúng thông tin xác thực trong mã nguồn. Bí mật nên đến từ một cơ chế thực thi được bảo vệ và cần được xác định phạm vi và luân chuyển theo chính sách của nhà cung cấp.
• Bỏ qua idempotency và các tác động trùng lặp. Một yêu cầu tạo ra hết thời gian có thể đã hoàn tất, vì vậy thiết kế biến đổi cần một cách tài liệu hóa để hòa giải kết quả.
• Giả định rằng mọi thành công đều giống nhau. Một số giao diện trả lại công việc đã được chấp nhận, dữ liệu một phần, cảnh báo hoặc định danh tác vụ không đồng bộ thay vì kết quả cuối cùng.
• Kết nối với hành vi không được tài liệu hóa. Thứ tự trường nội bộ, tiêu đề ngẫu nhiên và các điểm cuối không được liệt kê có thể thay đổi mà không có lời hứa tương thích.

APIs trong Quy trình Dữ liệu Web

Một API có cấu trúc có thể loại bỏ việc phân tích trình duyệt khỏi quy trình làm việc bằng cách trả về các bản ghi trực tiếp. Điều đó hoạt động khi nhà cung cấp công khai dữ liệu cần thiết và các điều khoản cho phép việc sử dụng dự kiến. Khi không có giao diện có cấu trúc phù hợp và thông tin có sẵn công khai, một hệ thống thu thập có thể cần một bước thu thập HTTP hoặc trình duyệt-rendering theo sau là trích xuất và chuẩn hóa.

Giữ việc thu thập, biến đổi và lưu trữ như các ranh giới tách biệt. Thành phần thu thập nên bảo tồn trạng thái nguồn và siêu dữ liệu liên quan. Việc biến đổi nên xác thực các trường và làm cho giá trị thiếu rõ ràng. Lưu trữ nên sử dụng các định danh ổn định và ghi lại nguồn gốc cần thiết cho việc quản trị. Sự tách biệt này ngăn chặn việc thay đổi định dạng nguồn làm hỏng dữ liệu phía hạ nguồn một cách im lặng.

Tài liệu hợp đồng phía khách hàng bên cạnh hợp đồng của nhà cung cấp: các hoạt động nào được sử dụng, trường nào là bắt buộc, khối lượng nào được mong đợi, cách cung cấp thông tin xác thực, và bằng chứng gì đánh dấu một kết quả hoàn chỉnh. Các bài kiểm tra nên bao gồm các tải trọng thành công và lỗi đại diện mà không phụ thuộc vào chi tiết thực hiện riêng tư.

Danh sách kiểm tra Đánh giá 'What Is an API'

Sử dụng các kiểm tra này để chuyển định nghĩa 'What Is an API' thành bằng chứng thực hiện mà một nhà phát triển, điều hành hoặc người đánh giá có thể tái sản xuất.

1. Nêu lại ranh giới. Đối với 'What Is an API', xác định người gọi, nhà cung cấp, đường dẫn và sự kiện chính xác đánh dấu một kết quả hoàn chỉnh.
2. Xác minh tuyên bố trung tâm. Xác nhận tuyên bố này với việc thực hiện và tài liệu của nó: Một API là một giao diện phần mềm đã được định nghĩa. Nó công khai các khả năng và quy tắc đã đặt tên để một thành phần có thể sử dụng thành phần khác mà không cần biết thực hiện bên trong của nó.
3. Theo dõi cơ chế. Ghi lại khám phá và hợp đồng, xử lý yêu cầu, diễn giải phản hồi, và ghi nhận thành phần nào sở hữu từng giai đoạn.
4. Kiểm tra sự phân biệt gần nhất. Tài liệu lý do tại sao Endpoint hoặc callable có nghĩa là “Nơi hoặc cách mà một hoạt động được giải quyết.” trong hệ thống này.
5. Kiểm tra một trường hợp sử dụng đại diện. Sử dụng tích hợp sản phẩm với dữ liệu thực tế, vị trí, khối lượng và ranh giới quyền.
6. Bảo vệ chống lại một sai lầm đã biết. Xem xét “Đối xử với các ví dụ như là toàn bộ sơ đồ.” và thêm một kiểm tra chấp nhận để bắt kịp nó.
7. Giới hạn khối lượng công việc. Đặt các giới hạn phù hợp với chủ đề cho What Is an API, bao gồm payload, độ đồng thời, thời gian thực thi và đầu ra lưu trữ khi chúng áp dụng.
8. Ghi lại quyết định. Giải thích tại sao What Is an API phù hợp với ranh giới này và nêu tên bằng chứng sẽ biện minh cho một cách tiếp cận khác sau đó.

Kết luận

What Is an API nên mô tả một phần thiết kế có thể kiểm tra được thay vì đóng vai trò như một nhãn lỏng lẻo cho hành vi lân cận. Việc xem xét nên bảo tồn quyết định trung tâm này: Một API là một giao diện phần mềm đã được xác định. Nó phơi bày các khả năng và quy tắc đã đặt tên để một thành phần có thể sử dụng thành phần khác mà không cần biết đến triển khai nội bộ của nó. Nó cũng nên bảo vệ việc coi các ví dụ như là toàn bộ sơ đồ. và giữ quyền truy cập What Is an API trong chính sách tài liệu cho giao diện hoặc mạng.