Một mặt phẳng điều khiển êm dịu hơn.

Mô hình tài nguyên rõ ràng

Một tích hợp nên hoạt động với mã định danh máy chủ, khu vực, image, gói và thao tác được chỉ định rõ ràng. Yêu cầu tạo và cài đặt lại nên trả về một thao tác có thể kiểm tra đến khi hoàn tất. Một yêu cầu HTTP thành công không đồng nghĩa với việc máy đã sẵn sàng.

Thông tin đăng nhập với công việc hạn chế

Các token API nên có thể thu hồi độc lập và bị giới hạn ở tài nguyên và hành động tối thiểu cần thiết. Lưu chúng trong trình quản lý bí mật hoặc môi trường được bảo vệ. Không bao giờ gửi token đến trình duyệt chỉ để tránh viết một backend nhỏ.

Thử lại phải an toàn

Có thể xảy ra hết thời gian chờ mạng sau khi một thao tác đã được chấp nhận. Sử dụng khóa idempotency cho các yêu cầu tạo và nhạy cảm với thanh toán, kiểm tra trạng thái thao tác và tuân thủ giới hạn tốc độ. Một lần thử lại nên giải quyết sự không chắc chắn, không tạo thêm một máy chủ tính phí.

Kiểm tra khả năng tương thích trước khi tích hợp

Kiểm tra phiên bản API đã phát hành, mô hình xác thực, định dạng lỗi, phân trang, giới hạn tốc độ và phạm vi token trước khi xây dựng tích hợp. Chỉ sử dụng các gói KoalaVPS SDK đã phát hành từ các liên kết phát hành đã xác minh.

Lộ trình API

Lộ trình API bao gồm khám phá danh mục, xác thực, trạng thái tài khoản, thanh toán crypto, vòng đời máy chủ, khóa SSH công khai và webhook. Các tuyến bên dưới mô tả hợp đồng giao diện; quyền truy cập sản xuất chưa khả dụng.

Các tuyến xác thực và tài khoản

Hợp đồng API tách biệt phiên đăng nhập và khóa API. Kiểm tra lược đồ phản hồi, lỗi, thời hạn token và các hành động khôi phục được hỗ trợ so với phiên bản phát hành cho tích hợp của bạn.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Danh mục và các tuyến thanh toán

Đọc danh mục không được yêu cầu thanh toán. Việc tạo thanh toán cần phạm vi thanh toán bị hạn chế, trạng thái hóa đơn rõ ràng và xử lý idempotent. Xác nhận phải hoàn tất trước khi kích hoạt dịch vụ.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Máy chủ và các tuyến truy cập

Vòng đời cần xác nhận rõ ràng cho các thao tác hủy và cài đặt lại. Khóa SSH riêng tư thuộc về máy khách; dịch vụ chỉ cần các khóa công khai tương ứng.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Sự kiện và thông tin công khai

Webhook cần chữ ký có thể xác minh, số lần thử lại có giới hạn và bảo vệ chống phát lại. Các điểm cuối tin cậy công khai nên trả về bằng chứng thực có ngày tháng thay vì đảm bảo tổng hợp.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Ủy quyền và giới hạn lưu lượng

Một mô hình phạm vi ứng viên gồm đọc, máy chủ, thanh toán và toàn quyền, với tối đa mười khóa hoạt động mỗi tài khoản. Hợp đồng API đề xuất hạn mức yêu cầu 120 mỗi phút và 3,000 mỗi giờ cho khóa API, và 30 mỗi phút cho lưu lượng công khai. Hãy kiểm tra HTTP 429, Retry-After và cửa sổ thực thi trong tài liệu API đã phát hành; các hạn mức lộ trình này không phải cam kết năng lực sản xuất.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK và các bản phát hành giao thức

Lộ trình tích hợp bao gồm REST, một endpoint MCP được lưu trữ, một gói stdio có phiên bản, các SDK và một CLI. Kiểm tra tính sẵn có của bản phát hành, runtime được hỗ trợ, checksum và khả năng tương thích API trước khi cài đặt máy khách. Bản tải xuống cho môi trường production hiện chưa có.

Tài nguyên API, được nhóm theo trách nhiệm

API dự kiến tách biệt truy cập tài khoản, đọc danh mục, thanh toán, vòng đời máy chủ, khóa SSH và callback. Các lệnh gọi chỉ đọc không nên tạo đơn hàng, và thông tin xác thực thanh toán không nên tự động cho phép thay đổi bảo mật tài khoản. Điều này mô tả hợp đồng tích hợp. Một điểm cuối cung cấp trong môi trường sản xuất và SDK đã phát hành không có sẵn qua trang web này.

• Tài khoản: phiên đăng nhập, mức sử dụng và sự kiện kiểm tra bảo mật
• Danh mục: gói, khu vực và hình ảnh khả dụng
• Máy chủ: tạo, kiểm tra, thay đổi và hủy
• Khóa SSH: đăng ký tài liệu công khai và thu hồi khóa lỗi thời
• Webhook: đăng ký, kiểm tra, thử nghiệm và xóa các callback đã ký

Yêu cầu máy chủ nên giữ nhỏ

Chọn một mã định danh gói tiêu chuẩn, khu vực, hình ảnh hệ điều hành và tên máy chủ. Giới hạn tên máy chủ dự kiến là 64 ký tự. Một dịch vụ đang hoạt động có thể tạo bí mật quản trị viên một cách riêng tư hoặc chấp nhận một khóa công khai SSH đã đăng ký. Yêu cầu gói tiêu chuẩn không ngụ ý việc bổ sung ổ đĩa, GPU, NIC và IP tùy ý. Từ chối các trường không được hỗ trợ thay vì âm thầm tính phí cho một nâng cấp phỏng đoán.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Phạm vi và giới hạn khóa là một phần của hợp đồng

Các nhóm đặc quyền được đề xuất là đọc, máy chủ, thanh toán và quản trị toàn bộ tài khoản. Một khóa nên được hiển thị một lần khi tạo, lưu trữ riêng tư và thu hồi độc lập với mật khẩu của người dùng. Giới hạn tài khoản dự kiến là mười khóa hoạt động. Trước khi công bố một triển khai, hãy xác minh rằng mỗi thao tác từ chối một khóa không có phạm vi cần thiết.

Công bố giới hạn tốc độ và hành vi thử lại cùng nhau

Các giới hạn đề xuất là 120 yêu cầu mỗi phút và 3,000 mỗi giờ cho một khóa API, và 30 yêu cầu mỗi phút cho các yêu cầu danh mục công khai chưa xác thực. Đây là các giá trị chính sách dự kiến, không phải năng lực API đã đo lường. Một triển khai thực tế cần phản hồi 429 nhất quán, hướng dẫn Retry-After và backoff phía máy khách có giới hạn. Các yêu cầu tạo và thanh toán cũng cần khóa idempotency ổn định.

Webhook là những thông điệp có thể đến nhiều lần

Bộ nhận callback nên xác minh chữ ký trên nội dung gốc, từ chối các dấu thời gian nằm ngoài cửa sổ cho phép và ghi nhớ các mã định danh sự kiện đã xử lý. Lưu bền sự kiện trước khi xác nhận, sau đó áp dụng thay đổi một cách bất biến. Giữ các lần thử giao hàng và một đường phát lại thủ công hiển thị. Callback là một quan sát về một thao tác, không phải quyền thực thi các chỉ thị không liên quan chứa trong một payload.

Kiểm toán mà không biến nhật ký thành kho bí mật

Ghi lại mã định danh tác nhân, loại thao tác, tài nguyên bị ảnh hưởng, kết quả và thời gian khi cần cho bảo mật tài khoản. Tránh ghi lại mật khẩu, token bearer, khóa riêng tư hoặc toàn bộ nội dung yêu cầu thanh toán và ứng dụng theo mặc định. Giữ rõ ràng về thời gian lưu giữ, quyền truy cập và lịch sử hiển thị cho khách hàng. Nhật ký kiểm toán bảo mật và quyền yêu cầu kiểm tra nội dung ứng dụng của khách hàng là hai điều khác nhau.

Chỉ phát hành sản phẩm khi chúng tồn tại

Một lần ra mắt API công khai nên bao gồm tài liệu OpenAPI có phiên bản, hướng dẫn xác thực, ví dụ lỗi và quy trình ngừng hỗ trợ. Một CLI, gói Python, máy khách TypeScript hoặc máy chủ MCP trong tương lai cần bản phát hành thực tế, checksum và tài liệu được duy trì. Gói cấp phát KoalaVPS hoặc điểm cuối quản lý sản xuất không được phát hành qua trang này.

Rõ ràng hơn một chút.