Chuyển sang địa chỉ API

Các tích hợp trước đây gọi API trên địa chỉ chính của Sursa, địa chỉ mà mọi người mở trong trình duyệt, ví dụ https://app.sursa.com/v1/…. Giờ đây API cũng có địa chỉ riêng, https://api.sursa.com trên đám mây hoặc https://api.<your domain> trong bản cài đặt của bạn. Địa chỉ này được xây dựng cho tích hợp: nó mở rộng theo chiều ngang sau một bộ cân bằng tải, và chỉ phục vụ API.

Bạn không bắt buộc phải chuyển. Địa chỉ chính vẫn tiếp tục phục vụ /v1 cho các tích hợp hiện có, không có ngày kết thúc và không chuyển hướng. Hãy chuyển khi thuận tiện cho bạn, để có được lợi ích của địa chỉ API, và dùng nó cho mọi tích hợp mới.

Những gì giữ nguyên

Đường dẫn, tham số, trường, mã lỗi và sự kiện: GET /v1/cards là cùng một yêu cầu trên cả hai địa chỉ.
Khóa API. Cùng các khóa kb_ và kbsrc_ hoạt động trên cả hai địa chỉ, với cùng vai trò, phạm vi quyền và hồ sơ dữ liệu.
Khóa idempotency, giới hạn tốc độ và hạn mức. Yêu cầu trên cả hai địa chỉ đều được tính vào cùng hạn mức của tổ chức.
Webhook. Lần gửi, chữ ký và khóa bí mật không phụ thuộc vào địa chỉ bạn gọi.
Liên kết trong phản hồi. doc_url của một lỗi trỏ tới cổng này, còn header Link của một trang danh sách trỏ tới địa chỉ API, dù bạn gọi địa chỉ nào.

Những gì khác trên địa chỉ API

Trên địa chỉ chính	Trên địa chỉ API
Mọi endpoint của ứng dụng web, kể cả endpoint nội bộ	Chỉ các endpoint của tài liệu tham chiếu API công khai. Mọi đường dẫn khác trả về `404` với mã `api.not_found`.
Khóa trong `X-API-Key` hoặc `Authorization`, hoặc cookie phiên của trình duyệt	Khóa hoặc token truy cập OAuth, tốt nhất trong `Authorization: Bearer`. Cookie bị bỏ qua.
`GET /auth/me`	`GET /v1/me`. Các đường dẫn dưới `/auth/` không được phục vụ.
Chế độ “View as” (Xem với tư cách) bằng cookie	Header `X-View-As`, cho khóa có vai trò `admin`.
Một máy chủ, hoặc một nhóm máy chủ cố định	Nhiều máy chủ sau một bộ cân bằng tải.

Hàng cuối chỉ quan trọng trong một trường hợp: câu trả lời dạng luồng của POST /v1/chat. Luồng bị ngắt chỉ tiếp tục từ Last-Event-ID trên máy chủ đang viết câu trả lời. Nếu tích hợp của bạn tiếp tục luồng, hãy gán cho mỗi câu hỏi một request_id, để lần thử lại trên máy chủ khác nhận được câu trả lời đã lưu thay vì một câu trả lời thứ hai. Xem Tiếp tục luồng bị ngắt.

Trước khi chuyển

Kiểm tra rằng mọi lệnh gọi đều công khai. Liệt kê các đường dẫn mà tích hợp của bạn gọi và tra từng đường dẫn trong tài liệu tham chiếu API, hoặc so sánh chúng với đặc tả của địa chỉ mới:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Đường dẫn không có trong tài liệu tham chiếu công khai thuộc về ứng dụng web. Nó vẫn hoạt động trên địa chỉ chính, nhưng không được phục vụ trên địa chỉ API, và dạng của nó không phải là cam kết công khai. Hãy thay nó bằng một endpoint công khai, hoặc giữ phần đó của tích hợp trên địa chỉ chính và cho đầu mối liên hệ của bạn tại Sursa biết bạn cần gì.

Kiểm tra cách bạn xác thực. Nếu tích hợp đăng nhập bằng mật khẩu của người dùng và cookie phiên, trước tiên hãy chuyển nó sang khóa API. Nếu nó gửi X-API-Key, việc chuyển sang Authorization: Bearer được khuyến nghị nhưng không bắt buộc.

Kiểm tra mạng của bạn. Cho phép HTTPS đi ra tới tên máy chủ mới trong tường lửa và proxy của bạn.

Chuyển từng bước

Đưa URL gốc vào phần cài đặt của tích hợp, nếu nó chưa được đặt ở đó.

Thử địa chỉ mới bằng một yêu cầu đọc:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Chạy bộ kiểm thử của tích hợp với địa chỉ mới, bằng khóa thử nghiệm và bộ sưu tập thử nghiệm.
Chuyển một phần lưu lượng, ví dụ một worker hoặc một môi trường, và theo dõi 404 api.not_found, 401 và 5xx trong nhật ký. Mọi phản hồi đều mang X-Request-Id; hãy lưu nó cùng nhật ký của bạn.
Chuyển phần còn lại. Giữ URL gốc cũ trong cấu hình một thời gian để có thể chuyển về trong vài giây.

Những điều cần kiểm tra sau khi chuyển

GET /v1/health trên địa chỉ mới trả về cùng version như trên địa chỉ cũ.
Phản hồi có các header RateLimit. Nếu tích hợp của bạn tự giảm tốc theo X-RateLimit-*, nó có thể tiếp tục làm như vậy: cả hai bộ header đều được gửi. Xem Giới hạn tốc độ và hạn mức.
Nếu tích hợp của bạn chạy trong trình duyệt, nó không còn cần proxy riêng cho CORS: địa chỉ API cho phép yêu cầu từ mọi origin, không có cookie.