API của Optifora hoạt động ra sao
Trang này mô tả hình dạng của API: danh tính được chứng minh ra sao, phiên bản tiến lên thế nào, một yêu cầu phải nằm trong giới hạn nào, lỗi trông ra sao, và dữ liệu được trao đổi với bên ngoài bằng cách nào.
Sản phẩm đang được phát triển và bề mặt API vẫn đang được hoàn thiện. Tài liệu tham chiếu cho các điểm cuối sẽ được công bố riêng; trang này không nêu địa chỉ và không có lời gọi mẫu, chỉ trình bày cơ chế.
Xác thực danh tính
Mỗi yêu cầu đều thuộc về một con người hoặc một ứng dụng đã đăng ký. Yêu cầu không mang danh tính khi chạm tới điểm cuối được bảo vệ sẽ bị trả về là chưa xác thực.
- Bearer tokenToken truy cập đi kèm trong tiêu đề authorization của yêu cầu. Token được ký và chỉ cho biết yêu cầu thuộc về ai.
- Vòng đời ngắnToken truy cập hết hạn sau một khoảng thời gian tính bằng phút; độ dài là thiết lập khi triển khai và mặc định là ba mươi phút.
- Làm mới và xoay vòngPhiên làm việc được gia hạn bằng token làm mới, và mỗi lần gia hạn sẽ cấp một cặp token mới. Nếu một token làm mới đã dùng lại được trình lần thứ hai, toàn bộ phiên của người đó bị thu hồi.
- Quyền hạn không được gắn cứng vào tokenToken chỉ mang danh tính; quyền xem của một người được hỏi lại cơ sở dữ liệu trong từng yêu cầu. Vì vậy một quyền bị rút lại sẽ ngừng hiệu lực trước khi token đang cầm hết hạn.
- Khóa của bên tích hợpMỗi ứng dụng đã đăng ký kết nối bằng khóa riêng của mình. Giá trị nguyên bản chỉ hiển thị một lần, tại thời điểm tạo; thứ được lưu lại là bản băm của khóa và tiền tố không bí mật giúp nhận diện khóa đó.
- Tổ chức là bên cấp quyền truy cậpDù một ứng dụng được dùng rộng rãi đến đâu, nếu tổ chức không ghi nhận quyền cấp phép thì ứng dụng đó không thấy được một dòng dữ liệu nào. Quyền cấp phép có thời hạn, có phạm vi và có thể thu hồi.
Quản lý phiên bản
- Phiên bản nằm trong đường dẫnCác điểm cuối được công bố sau một tiền tố phiên bản; bề mặt hôm nay là phiên bản một.
- Thay đổi phá vỡ tương thích sẽ mở đường dẫn mớiHợp đồng của một điểm cuối đang có không bị phá vỡ tại chỗ. Thay đổi không tương thích được công bố trên một đường dẫn phiên bản mới, trong khi đường dẫn cũ vẫn hoạt động.
- Tài liệu tự nêu phiên bản của mìnhTài liệu tham chiếu mang theo số phiên bản mà nó được sinh ra từ đó; câu hỏi đang đọc phiên bản nào do chính tài liệu trả lời.
Môi trường và giới hạn
Tài liệu tham chiếu khai báo hai môi trường: môi trường vận hành thật và môi trường phát triển cục bộ. Địa chỉ gốc được trao cho bên tích hợp cùng với khóa của họ; địa chỉ đó không được công bố trên trang này.
- Sự sống và sự sẵn sàng được đo riêngMột điểm cuối cho biết tiến trình còn sống; điểm cuối thứ hai gửi một truy vấn thật tới cơ sở dữ liệu và xác nhận là kết nối được. Chỉ điểm cuối thứ hai mới quyết định có nên dồn lưu lượng sang hay không.
- Nguồn gốc trình duyệt bị giới hạn theo danh sáchYêu cầu khác nguồn gốc chỉ được chấp nhận từ những nguồn đã khai báo trước; khi danh sách còn trống, yêu cầu khác nguồn gốc từ trình duyệt sẽ bị từ chối.
- Giới hạn phần thânPhần thân của một yêu cầu không được vượt quá năm megabyte. Tập dữ liệu lớn đi theo dạng tác vụ chuyển hàng loạt có bản ghi trạng thái riêng, chứ không phải một yêu cầu đơn lẻ.
- Thông tin bí mật không được ghi vào nhật kýNhật ký máy chủ không lưu tiêu đề authorization, không lưu cookie, không lưu mật khẩu và không lưu số định danh cá nhân.
Giới hạn tần suất
Giới hạn được tính theo từng địa chỉ và theo từng phút. Mặc định là 120 yêu cầu mỗi phút và được đặt khi triển khai. Phần hạn mức còn lại được báo trong tiêu đề của mọi phản hồi.
| Tiêu đề phản hồi | Nội dung cho biết |
|---|---|
| x-ratelimit-limit | Tổng hạn mức bên trong một cửa sổ. |
| x-ratelimit-remaining | Số lượt còn lại trong cửa sổ hiện tại. |
| x-ratelimit-reset | Số giây còn lại cho tới khi hạn mức được làm mới. |
| retry-after | Cần chờ bao nhiêu giây trước khi thử lại. Chỉ xuất hiện trên phản hồi đã từ chối yêu cầu. |
Khi vượt quá giới hạn, yêu cầu bị từ chối và phản hồi cho biết cần chờ bao nhiêu giây. Việc thử lại được thực hiện sau khoảng thời gian đó, không phải ngay lập tức.
Định dạng lỗi
Mọi lỗi đều trở về trong cùng một khuôn: một trường mã ngắn để máy rẽ nhánh, và một trường giải thích để con người đọc.
- errorMã ngắn để phía gọi rẽ nhánh xử lý.
- messagePhần giải thích điều đã xảy ra.
| Trạng thái | Trường mã | Ý nghĩa |
|---|---|---|
| 400 | Bad Request | Yêu cầu không khớp với lược đồ. Phần giải thích nêu rõ trường bị thiếu hoặc không hợp lệ. |
| 401 | unauthenticated | Không có danh tính hợp lệ: không gửi token, token đã hết hạn, hoặc token không xác minh được. |
| 404 | Not Found | Không có điểm cuối như vậy, hoặc không có bản ghi như vậy. |
| 429 | Too Many Requests | Đã vượt giới hạn tần suất; phản hồi cho biết cần chờ bao lâu. |
| 5xx | internal_error | Một sự cố ngoài dự kiến. Chi tiết không được trao cho phía gọi; nó được ghi vào nhật ký máy chủ. |
Phân trang
Các điểm cuối trả về danh sách đều nhận cùng hai tham số và trả về cùng những bộ đếm, nhờ vậy phía gọi không phải viết lại phần phân trang cho từng điểm cuối.
- limitMột trang chứa bao nhiêu bản ghi. Ít nhất là một, nhiều nhất là hai trăm; là năm mươi khi không đặt.
- offsetBỏ qua bao nhiêu bản ghi. Bắt đầu từ không.
- totalTổng cộng có bao nhiêu bản ghi khớp với bộ lọc.
- countPhản hồi này thực sự mang theo bao nhiêu bản ghi.
Phản hồi cũng lặp lại giá trị limit và offset đã dùng; phía gọi đọc vị trí của mình từ câu trả lời thay vì phải đoán.
Trao đổi dữ liệu và webhook
Chế độ trao đổi là một thiết lập, không phải một sản phẩm riêng: mỗi ứng dụng đã đăng ký đều mang chế độ hoạt động của mình ngay trên bản ghi của nó.
| Chế độ | Ý nghĩa |
|---|---|
| Một chiều — đi ra | Optifora công bố dữ liệu; phía kia đọc dữ liệu đó hoặc đăng ký nhận sự kiện. |
| Một chiều — đi vào | Phía kia đẩy dữ liệu sang; Optifora kiểm tra tính hợp lệ rồi ghi lại. |
| Hai chiều | Cả hai phía cùng ghi; quy tắc xử lý xung đột được định nghĩa trước. |
| Bắt tay | Mỗi lần chuyển dữ liệu đều mở một phiên: đề nghị, xác minh, phê duyệt, chuyển giao và biên nhận. Biên nhận được lưu ở cả hai phía. |
- Sự kiện được đẩy ra ngoàiWebhook gửi sự kiện tới địa chỉ gọi lại mà ứng dụng đã đăng ký khai báo. Sự kiện không gửi được sẽ nằm trong hàng đợi và được thử lại; nó không bao giờ bị bỏ đi trong im lặng.
- Cùng một yêu cầu không ghi hai lầnYêu cầu ghi mang theo một khóa idempotency. Yêu cầu thứ hai với cùng khóa đó không tạo thêm bản ghi thứ hai.
- Mọi lời gọi đều được đoAi gọi, gọi lúc nào, với phạm vi nào và kết quả ra sao — tất cả đều được ghi lại. Cùng bản ghi đó trả lời cả việc gỡ lỗi lẫn câu hỏi ai đã lấy dữ liệu này.
- Ứng dụng của chúng tôi đi qua cùng một cánh cửaKhông tồn tại con đường thứ hai có đặc quyền. Chính phần tích hợp của chúng tôi là bằng chứng cho bề mặt mà một nhà phát triển bên ngoài gặp phải.
Mô hình dữ liệu cho lớp trao đổi đã sẵn sàng; các điểm cuối của nó chưa được công bố. Khi được công bố, mục này sẽ dẫn tới các mục tương ứng trong tài liệu tham chiếu.
Tài liệu tham chiếu
Tài liệu tham chiếu không được viết tay; nó được sinh ra từ lược đồ của các điểm cuối. Khi mỗi điểm cuối bàn giao lược đồ của mình, tài liệu tự đầy lên, nhờ vậy tài liệu và hành vi thực tế không thể lệch nhau.
- Hôm nay: đang chuẩn bịCác lược đồ đang được chuyển sang theo từng phân hệ. Trước khi tài liệu được công bố, yêu cầu và phản hồi của mọi điểm cuối sẽ hiện diện trong đó.
- Sẽ công bố ở hai định dạngMột tài liệu OpenAPI máy đọc được, và một trang tham chiếu sinh ra từ chính tài liệu đó, có thể xem trong trình duyệt.
- Quyền truy cập chia theo tầngPhần tổng quan mở cho tất cả. Tài liệu tham chiếu đầy đủ có thể nằm sau một token tài liệu cấp cho bên tích hợp đã đăng ký; khóa vận hành thật và địa chỉ gọi lại hoàn toàn không thuộc phạm vi tài liệu — chúng thuộc về bản ghi của ứng dụng.
- Chuẩn địa chỉHai tài liệu tham chiếu được công bố và địa chỉ của chúng là cố định: client-api.optifora.com/docs mở cho mọi người, admin-api.optifora.com/docs đòi hỏi quyền và đóng với bên ngoài. Hôm nay chưa địa chỉ nào hoạt động; các liên kết sẽ được thêm vào mục này khi chúng hoạt động.
Nếu kế hoạch tích hợp đã rõ ràng, hãy viết cho chúng tôi từ trang liên hệ: tổ chức của bạn sẽ nằm trong nhóm được báo tin đầu tiên khi bề mặt API mở.
Bạn có một đề nghị cụ thể?
Những trang này giải thích quy trình hỗ trợ vận hành ra sao. Nếu bạn có một đề nghị hay một câu hỏi, hãy viết cho chúng tôi từ trang liên hệ.
Tới trang liên hệ