Địa chỉ API và môi trường

Sursa API có địa chỉ riêng, tách biệt với địa chỉ mọi người dùng để mở Sursa trong trình duyệt. Mọi đường dẫn đều bắt đầu bằng /v1.

Nơi Sursa chạy	Địa chỉ API	Cổng này
Đám mây Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Bản cài đặt của bạn	`https://api.<your domain>`, theo thiết lập của quản trị viên	`/developers/` trên địa chỉ API
Bản cài đặt của bạn không có địa chỉ API riêng	địa chỉ chính của bản cài đặt	`/developers/` trên địa chỉ chính

Địa chỉ API chỉ phục vụ API: trên đó không có trang đăng nhập, không có cookie và không có giao diện web. Mọi yêu cầu được xác thực bằng khóa API hoặc token truy cập OAuth. Địa chỉ này có thể được phục vụ bởi nhiều máy chủ đứng sau một bộ cân bằng tải; tích hợp của bạn không cần biết có bao nhiêu máy chủ.

Các tích hợp gọi API trên địa chỉ chính (ví dụ https://app.sursa.com/v1) vẫn tiếp tục hoạt động. Xem Chuyển sang địa chỉ API để biết một vài khác biệt và các bước chuyển đổi.

URL gốc

Hãy tạo mọi yêu cầu từ một URL gốc duy nhất trong cấu hình của bạn, để cùng một đoạn mã chạy được với bất kỳ môi trường nào:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Chỉ dùng HTTPS, và đừng để khóa lọt vào nhật ký của các yêu cầu bạn gửi.

Phiên bản và đặc tả

GET /v1/health cho biết địa chỉ có đang hoạt động hay không và trả về phiên bản Sursa phục vụ địa chỉ đó. Endpoint này trả lời mà không cần khóa, nên bạn có thể dùng nó để giám sát:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Đây là phiên bản của bản phát hành Sursa, không phải của API. Phiên bản của API là info.version trong đặc tả của nó. Đặc tả OpenAPI 3.1 của API được công bố ở cùng địa chỉ, không cần xác thực:

Đường dẫn	Nội dung
`GET /openapi.json`	Đặc tả công khai, với địa chỉ này trong `servers`.
`GET /v1/openapi-public.json`	Cùng đặc tả đó. Hỗ trợ `ETag` và `If-None-Match`.

Hãy dùng nó để tạo client, để nhập API vào một công cụ như Postman, hoặc để kiểm tra trong CI rằng tích hợp của bạn chỉ dùng các thao tác của phiên bản bạn mong đợi. Tài liệu tham chiếu API của cổng này được xây dựng từ chính tệp đó.

Kiểm thử

Sursa không có chế độ thử nghiệm riêng: mọi yêu cầu có khóa đều tác động lên dữ liệu thật của tổ chức. Để phát triển và kiểm thử an toàn:

Tạo một khóa riêng cho phát triển với vai trò và phạm vi quyền hẹp nhất mà công việc cần.
Ghi vào một bộ sưu tập dành riêng, ví dụ sandbox, mà chỉ đội của bạn nhìn thấy, và xóa nó khi xong việc.
Nếu công ty bạn có tổ chức hoặc bản cài đặt Sursa riêng để kiểm thử, hãy trỏ URL gốc và khóa tới đó. Không có gì khác trong mã của bạn thay đổi.
Làm cho việc thử lại an toàn ngay từ đầu: gửi Idempotency-Key với mỗi yêu cầu POST và PATCH.

Bảng Dùng thử trên mỗi trang endpoint của tài liệu tham chiếu API gửi yêu cầu thật với khóa mà bạn dán vào. Khóa chỉ được giữ trong bộ nhớ của tab trình duyệt và chỉ được gửi tới địa chỉ API.

Yêu cầu về mạng

HTTPS đi ra (cổng 443) từ máy chủ của bạn tới địa chỉ API.
Trong quy tắc tường lửa, hãy cho phép theo tên máy chủ thay vì địa chỉ IP cố định, nếu mạng của bạn cho phép: các máy chủ đứng sau địa chỉ này có thể thay đổi khi năng lực được bổ sung.
Ứng dụng trên trình duyệt có thể gọi API trực tiếp: phản hồi cho phép mọi origin (Access-Control-Allow-Origin: *) và không dùng cookie. Hãy lưu ý rằng khóa dùng trong trình duyệt sẽ hiển thị với người dùng trình duyệt đó.