고객 패널에서 발급하는 토큰 하나
bearer 토큰 형태로 전송됩니다. 원하시면 읽기 전용으로 제한하거나 단일 서비스로 범위를 한정할 수 있습니다. 토큰은 비밀번호와 무관하며, 하나를 취소해도 로그아웃되지 않습니다.
API 토큰 하나로, 패널이 할 수 있는 모든 것
HTTPS 기반 JSON입니다. SDK도, 별도의 개발자 계정도 필요 없으며, 패널에는 있는데 여기에는 없는 엔드포인트도 없습니다.
서버 생성
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'즉시 빌드 ID를 반환합니다. 약 60초 후 머신이 SSH로 응답하며, 자격 증명이 전송되기 전에 주소가 라우팅됩니다.
20개의 엔드포인트
전체 항목, 다섯 개 그룹으로
기본 URL https://api.vpsoffshore.com/v1. 경로에 버전이 포함되어 있어 v2가 나와도 v1은 계속 작동하며, 중단일은 1년 전에 공지됩니다.
서버
GET
/servers
계정의 모든 서비스를 상태, 요금제, 주소와 함께 확인할 수 있습니다.
POST
/servers
새로 생성합니다. 빌드 ID와 함께 즉시 응답하며, 약 1분 후 서버에 접속할 수 있습니다.
GET
/servers/{id}
지난 1시간의 실시간 리소스 사용량을 포함한 서비스 1개.
PATCH
/servers/{id}
요금제를 변경하십시오. 디스크 여건이 허용하는 범위에서 재설치 없이 크기를 조정합니다.
DELETE
/servers/{id}
삭제합니다. 디스크는 14일간 보관된 뒤 재발급 전에 완전히 삭제됩니다.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
스토리지
GET
/servers/{id}/snapshots
특정 서비스의 스냅샷, 최신순.
POST
/servers/{id}/snapshots
스냅샷을 생성하십시오. 씬 프로비저닝 방식이라 빠르고 디스크 사용량이 두 배로 늘지 않습니다.
POST
/snapshots/{id}/restore
동일한 위치에 복원하거나, 같은 요금제 이상의 다른 서비스에 복원할 수 있습니다.
DELETE
/snapshots/{id}
스냅샷을 삭제합니다.
네트워크
GET
/servers/{id}/addresses
서비스에 라우팅된 주소, v4 및 v6.
POST
/servers/{id}/addresses
추가 주소 또는 /29를 요청하십시오.
PUT
/addresses/{ip}/rdns
리버스 DNS 설정. 다음 존 갱신을 기다리지 않고 1분 이내에 적용됩니다.
GET
/servers/{id}/bandwidth
전송량 카운터입니다. 참고용이며 초과할 수 있는 할당량은 존재하지 않습니다.
카탈로그
GET
/plans
모든 요금제를 사양과 가격까지 포함해 제공합니다. 이 사이트가 렌더링하는 원본과 동일한 데이터입니다.
GET
/images
직접 업로드한 항목을 포함해 사용 가능한 이미지 및 ISO 목록입니다.
POST
/images
URL로 ISO를 업로드하십시오. 콘솔이 연결된 상태로 부팅됩니다.
청구
GET
/invoices
청구서를 결제 완료분과 미결제분으로, 코인 및 체인 트랜잭션 정보와 함께 확인할 수 있습니다.
POST
/invoices/{id}/pay
지원되는 코인 8개 중 하나로 결제 주소를 발급합니다.
GET
/credits
적용된 SLA 보상 내역을, 이를 발생시킨 장애와 함께 확인할 수 있습니다.
패널에서 할 수 있는 모든 것이 여기에도 있으며, 여기에 있는 것 중 패널에 없는 것은 없습니다. 둘이 일치하지 않는다면 그것은 버그입니다 — 패널에서 알려 주십시오. 의도된 동작으로 문서화하는 대신 수정하겠습니다.
작동 방식
1시간 이내에 체감하게 될 네 가지 결정
API는 정상 경로가 아니라 오류 경로로 평가됩니다. 아래 네 가지 중 세 가지는 문제가 발생했을 때 일어나는 일에 관한 것입니다.
JSON 입력, JSON 출력, SDK 불필요
커스텀 봉투도, XML 폴백도, 서명 절차도 없는 순수 HTTPS입니다. curl로 가능하다면 그것으로 이미 클라이언트가 있는 것입니다. Go, Python, TypeScript용 공식 라이브러리가 있지만 어느 것도 필수는 아닙니다.
실수로는 걸리지 않는 요청 제한
토큰당 분당 600건, 생성 호출은 분당 60건까지 허용됩니다. 모든 응답은 헤더에 남은 한도를 포함하며, 초과 시 대기할 초 단위 시간과 함께 429를 반환합니다 — 조용히 사라지는 일은 없습니다.
무엇을 해야 하는지 알려주는 오류 메시지
4xx 응답에는 기계가 읽을 수 있는 코드, 사람이 이해할 수 있는 문장, 오류가 발생한 필드가 포함됩니다. 추측해야 하는 짧은 오류보다는 차라리 긴 오류를 반환하는 편을 택합니다.
한 번만 작성하면 되는 두 가지
인증, 그리고 오류가 어떻게 나타나는지
두 문서 모두 첫 번째 실패 이후가 아니라 첫 번째 호출을 작성하기 전에 읽어볼 가치가 있습니다.
인증하기
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"토큰은 패널에서 발급되며 읽기 전용이나 특정 서비스로 범위를 제한할 수 있습니다. 비밀번호와는 독립적이며, 토큰 하나를 취소해도 어디에서도 로그아웃되지 않습니다.
요청 제한 확인하기
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41실패한 응답에만이 아니라 모든 응답에 포함됩니다. 한도를 초과하면 대기해야 할 초 단위 시간과 함께 429가 반환되며, 조용히 요청이 버려지거나 응답이 축소되는 일은 결코 없습니다.
오류는 해당 필드를 알려줍니다
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}기계가 읽을 수 있는 코드, 사람이 이해할 수 있는 문장, 그리고 문제가 된 필드가 함께 제공됩니다. 추측해야 하는 짧은 오류보다 긴 오류가 비용이 덜 듭니다.
구성 폴링
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statebuilding → running으로 진행됩니다. 아무것도 생성하기 전에 등록해야 하는 웹훅은 없으며, 초당 1회의 폴링은 제한 범위 내에 있습니다.
신청할 것이 없습니다
토큰은 고객 패널 안에 있으며, 그 패널은 첫 서버와 함께 제공됩니다.
개발자 계정도, 승인 절차도, 프로덕션과 다르게 동작하는 샌드박스도 없습니다.