API 문서

Alpacon은 서버의 상태를 제어하고 관리할 수 있는 RESTful API를 제공합니다. API의 루트 경로는 /api/입니다.

API 엔드포인트

각 워크스페이스는 전용 API 엔드포인트를 갖습니다:

https://<workspace>.<region>.alpacon.io/api/

여기서:

  • <workspace>: 워크스페이스 슬러그
  • <region>: 워크스페이스 리전 (생성 시 할당)

예시: https://mycompany.us1.alpacon.io

💡 엔드포인트 확인하기: Personal Settings에서 워크스페이스 엔드포인트 URL 전체를 확인할 수 있습니다.

이 문서의 모든 API 예시는 https://your-workspace.us1.alpacon.io를 placeholder로 사용합니다. 실제 워크스페이스 엔드포인트로 대체하세요.

인증

모든 API 요청에는 API 토큰이 필요합니다. Authorization 헤더에 토큰을 포함하세요:

Authorization: token="alpat-xxxxxxxxxxxxxxxxxx"

토큰은 API 토큰 페이지에서 생성 및 관리하거나, Alpacon 웹 콘솔의 Personal Settings > API tokens에서 관리할 수 있습니다.

전역 정보

HTTP 메서드

메서드용도
GET리소스 목록 조회 또는 단일 조회
POST리소스 생성
PUT리소스 전체 교체
PATCH리소스의 특정 필드 수정
DELETE리소스 삭제

자세한 내용은 MDN HTTP 메서드 레퍼런스를 참조하세요.

URL 구조

API는 다음과 같은 URL 구조를 따릅니다:

  • 목록 조회 또는 생성: /api/<collection>/<resource>/
  • 단일 조회, 수정, 삭제: /api/<collection>/<resource>/<id>/
  • 추가 액션: /api/<collection>/<resource>/<id>/<action>/

예를 들어, GET /api/iam/users/a540bf0f-8b37-4f03-8546-dd71c6b03329/는 해당 사용자의 상태를 조회합니다.

※ 모든 API URL은 슬래시(/)로 끝납니다.

상태 코드

성공 코드:

코드의미일반적인 메서드
200 OK요청 성공GET, PUT, PATCH
201 Created리소스 생성됨POST
204 No Content리소스 삭제됨DELETE

오류 코드:

코드의미
400 Bad Request잘못된 요청 데이터. 필드별 상세 내용은 에러 메시지를 참조하세요.
401 Unauthorized인증되지 않음. 유효한 자격 증명 또는 토큰을 제공하세요.
403 Forbidden권한 없음. 인증된 사용자이지만 해당 작업에 대한 권한이 부족합니다.
404 Not Found리소스가 존재하지 않음.
405 Method Not Allowed이 엔드포인트에서 지원하지 않는 HTTP 메서드.
500 Server Error서버 내부 오류.

HTTP 상태 코드의 전체 목록은 MDN HTTP 상태 코드 레퍼런스를 참조하세요.

에러 메시지

앞서 언급한 바와 같이, 400 Bad Request가 발생할 경우 Alpacon은 필드별 에러 메세지와 non-field_errors 에러 메세지를 JSON 형태로 제공합니다.

예를 들어, 사용자의 비밀번호를 변경할 때 비밀번호가 서버 측 검증을 통과하지 못하면 아래와 같은 에러가 발생할 수 있습니다. 필드 이름(password)이 에러 메시지의 키로 사용됩니다. 클라이언트는 이 메시지를 파싱해 사용자에게 적절히 안내해야 합니다.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
  "password": [
    "비밀번호가 너무 짧습니다. 최소 8자 이상이어야 합니다.",
    "비밀번호가 너무 흔합니다.",
    "비밀번호가 모두 숫자로만 이루어져 있습니다."
  ]
}

non-field_errors는 개체 수준의 검증 실패 시 발생합니다. 예를 들어, 그룹의 소유자를 삭제하려 할 때 해당 사용자가 유일한 소유자인 경우, 다음과 같은 오류가 반환됩니다. 이 경우에는 non_field_errors 키가 사용됩니다.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
  "non_field_errors": [
    "현재 사용자는 그룹의 유일한 소유자입니다. 삭제를 진행하려면 다른 소유자를 추가하세요."
  ]
}

Alpacon 주요 기능

다음 문서들은 각 API 컬렉션에 대한 세부 정보를 제공합니다.

API 토큰
명령어
서버
IAM