Một token cho API, và mọi thứ bảng điều khiển làm được

JSON qua HTTPS. Không cần SDK, không cần tài khoản nhà phát triển riêng, và không có endpoint nào tồn tại trong bảng điều khiển mà không có ở đây.

Các endpoint Lấy token

Tạo máy chủ

curl -X POST https://api.vpsoffshore.com/v1/servers \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"plan":"reef","image":"debian-13"}'

Trả về ngay một build id. Máy phản hồi qua SSH khoảng sáu mươi giây sau, và địa chỉ được định tuyến trước khi thông tin đăng nhập được gửi đi.

20 điểm cuối

Mọi thứ, trong năm nhóm

URL cơ sở https://api.vpsoffshore.com/v1. Được đánh số phiên bản trong đường dẫn; v1 sẽ tiếp tục hoạt động khi v2 xuất hiện, và ngày ngừng hỗ trợ sẽ được thông báo trước một năm.

Máy chủ

GET /servers Mọi dịch vụ trong tài khoản, kèm trạng thái, gói và địa chỉ.

POST /servers Tạo máy. Trả về ngay lập tức kèm theo build id; máy chủ có thể truy cập được khoảng một phút sau đó.

GET /servers/{id} Một dịch vụ, bao gồm mức sử dụng tài nguyên trực tiếp trong giờ vừa qua.

PATCH /servers/{id} Thay đổi gói. Thay đổi cấu hình mà không cần cài đặt lại khi ổ đĩa cho phép.

DELETE /servers/{id} Xóa máy. Ổ đĩa được giữ trong 14 ngày, sau đó bị xóa sạch trước khi cấp lại.

POST /servers/{id}/actions reboot · shutdown · start · rebuild · rescue · reset-password.

Lưu trữ dữ liệu

GET /servers/{id}/snapshots Các bản chụp cho một dịch vụ, mới nhất trước.

POST /servers/{id}/snapshots Hãy tạo một bản. Gọn nhẹ, nên nhanh và không làm tăng gấp đôi dung lượng ổ đĩa của bạn.

POST /snapshots/{id}/restore Khôi phục tại chỗ, hoặc sang một dịch vụ khác cùng gói hoặc lớn hơn.

DELETE /snapshots/{id} Xóa một bản chụp.

Kết nối mạng

GET /servers/{id}/addresses Các địa chỉ được định tuyến đến một dịch vụ, v4 và v6.

POST /servers/{id}/addresses Yêu cầu một địa chỉ bổ sung, hoặc một dải /29.

PUT /addresses/{ip}/rdns Thiết lập reverse DNS. Có hiệu lực trong vòng một phút, không phải đến lần làm mới vùng DNS tiếp theo.

GET /servers/{id}/bandwidth Bộ đếm lưu lượng. Chỉ mang tính thông tin — không có hạn mức để vượt quá.

Danh mục

GET /plans Mọi gói kèm thông số kỹ thuật và giá. Cùng một nguồn dữ liệu mà trang này hiển thị từ đó.

GET /images Các hình ảnh và ISO có sẵn, bao gồm cả những hình ảnh bạn đã tải lên.

POST /images Tải lên ISO qua URL. Khởi động kèm theo bảng điều khiển.

Thanh toán

GET /invoices Hóa đơn, đã thanh toán và còn nợ, kèm đồng tiền và giao dịch trên chuỗi.

POST /invoices/{id}/pay Tạo địa chỉ thanh toán cho một trong 8 loại đồng tiền được chấp nhận.

GET /credits Bồi hoàn SLA đã áp dụng, cùng sự cố đã tạo ra từng khoản.

Mọi việc bảng điều khiển có thể làm đều có ở đây, và không gì ở đây bị thiếu trên bảng điều khiển. Khi hai bên không khớp nhau, đó là một lỗi — hãy báo cho chúng tôi từ bảng điều khiển và lỗi đó sẽ được sửa thay vì được ghi lại như một hành vi có chủ đích.

Cách nó hoạt động

Bốn quyết định bạn sẽ nhận thấy trong vòng một giờ

Một API được đánh giá qua các đường lỗi của nó, chứ không phải các đường thành công. Ba trong số bốn mục dưới đây nói về những gì xảy ra khi có sự cố.

Một token, được tạo trong bảng điều khiển

Được gửi dưới dạng bearer token. Bạn có thể giới hạn phạm vi chỉ đọc hoặc cho một dịch vụ duy nhất nếu muốn; token độc lập với mật khẩu của bạn và việc thu hồi một token không bao giờ khiến bạn bị đăng xuất.

JSON đầu vào, JSON đầu ra, không cần SDK

HTTPS thuần túy, không có envelope tùy chỉnh, không dự phòng XML và không có nghi thức ký phức tạp. Nếu curl làm được, bạn đã có một client. Có thư viện chính thức cho Go, Python và TypeScript, nhưng không bắt buộc phải dùng bất kỳ thư viện nào trong số đó.

Giới hạn tần suất mà bạn sẽ không vô tình chạm phải

600 yêu cầu mỗi phút cho mỗi token, 60 yêu cầu cho các lệnh gọi tạo. Mỗi phản hồi đều mang ngân sách còn lại trong một header, và khi vượt quá sẽ trả về 429 kèm số giây cần chờ — không bao giờ âm thầm bị bỏ qua.

Lỗi cho biết cần làm gì

Một mã 4xx mang theo một mã máy có thể đọc được, một câu mô tả dễ hiểu, và trường bị lỗi. Chúng tôi thà trả về một lỗi dài còn hơn một lỗi ngắn khiến bạn phải đoán.

Hai điều bạn chỉ cần viết một lần

Xác thực, và một lỗi trông như thế nào

Cả hai đều đáng đọc trước khi viết lệnh gọi đầu tiên, thay vì sau lần thất bại đầu tiên.

Xác thực

curl https://api.vpsoffshore.com/v1/servers \
  -H "Authorization: Bearer $TOKEN"

Token được tạo trong bảng điều khiển và có thể giới hạn phạm vi ở chế độ chỉ đọc hoặc cho một dịch vụ duy nhất. Chúng độc lập với mật khẩu của bạn, và thu hồi một token không đăng xuất bạn khỏi bất kỳ nơi nào.

Đọc giới hạn tần suất

X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41

Trên mọi phản hồi, không chỉ phản hồi bị lỗi. Vượt quá giới hạn sẽ trả về 429 kèm số giây cần chờ, không bao giờ âm thầm loại bỏ và không bao giờ rút ngắn phản hồi.

Một lỗi sẽ cho bạn biết đó là trường nào

{"error":"plan_unknown",
 "message":"No plan named 'reff'. Did you mean 'reef'?",
 "field":"plan"}

Một mã máy có thể đọc được, một câu mô tả cho con người và trường dữ liệu gây lỗi. Thông báo lỗi dài luôn rẻ hơn thông báo ngắn phải đoán ý.

Truy vấn trạng thái một cấu hình

curl https://api.vpsoffshore.com/v1/servers/$ID \
  -H "Authorization: Bearer $TOKEN" | jq .state

Chuyển từ building → running. Không có webhook nào bạn phải đăng ký trước khi có thể tạo bất cứ thứ gì, và polling một lần mỗi giây vẫn nằm trong giới hạn.

Không cần xin duyệt gì cả

Token nằm trong bảng điều khiển, và bảng điều khiển đi kèm với máy chủ đầu tiên

Không cần tài khoản nhà phát triển, không cần phê duyệt, không có sandbox nào hoạt động khác với production.

Bắt đầu với một máy chủ Mục lục tài liệu

Đọc tiếp

Tiếp theo nên xem gì