API 문서

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

API 엔드포인트

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

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

여기서:

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

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

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

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

인증

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

Authorization: token="alpat-xxxxxxxxxxxxxxxxxx"

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

전역 정보

HTTP 메서드

자세한 내용은 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은 슬래시(/)로 끝납니다.

상태 코드

성공 코드:

오류 코드:

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

에러 메시지

모든 400 Bad Request에는 기계가 읽을 수 있는 code가 포함되며, 문제를 특정 필드에 연결할 수 있는 경우 field_errors가 추가로 포함됩니다. 특정 필드에 속하지 않는 오류는 field_errors 안의 non_field_errors 키로 표시됩니다. 다른 오류 상태는 해당 검사가 이 코드화된 형식으로 전환된 경우에만 code를 포함합니다. 어떤 응답이 전환되었는지는 위의 상태 코드 표와 각 엔드포인트의 오류 표를 참조하세요.

예를 들어 사용자의 비밀번호를 변경할 때 새 비밀번호가 서버 측 검증을 통과하지 못하면 아래와 같은 응답을 받게 됩니다. 필드 이름(new_password)이 field_errors 안의 키로 사용됩니다. 연동은 message가 아니라 code를 기준으로 만드세요. message는 “Invalid input.”처럼 범용적인 문자열인 경우가 많고, 항상 영어로 고정되어 있지도 않습니다.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
  "code": "password_too_short",
  "field_errors": {
    "new_password": [
      {
        "code": "password_too_short",
        "message": "Invalid input."
      }
    ]
  }
}

field_errors는 각 필드를 {code, message} 항목의 목록에 매핑합니다. 한 필드에서 여러 검증이 동시에 실패하면 항목이 여러 개 담길 수 있습니다.

특정 필드 하나에 속하지 않는 오류(예: 요청의 여러 값을 함께 보는 객체 수준 규칙)는 필드 이름 대신 field_errors 안의 non_field_errors 키로 표시됩니다.

{
  "code": "approval_superuser_approve_required",
  "field_errors": {
    "non_field_errors": [
      {
        "code": "approval_superuser_approve_required",
        "message": "Invalid input."
      }
    ]
  }
}

400 응답이 모두 field_errors를 포함하는 것은 아닙니다. 특정 필드 없이 발생하는 검증 실패(예: 그룹에 남은 마지막 소유자를 삭제하려는 경우)는 최상위 code만 포함합니다.

{
  "code": "user_unique_group_owner"
}

거부 응답

이미 code가 포함된 402, 403, 405, 429 응답에는 요청이 거부된 이유를 설명하는 두 필드가 추가로 포함될 수 있습니다.

• gate: 요청을 거부한 제어의 종류
• missing: 있었다면 요청이 통과했을 전제 조건의 종류. 토큰 스코프 거부의 경우에 한해, 자격 증명에 없는 정확한 스코프 문자열이 들어갑니다.

두 필드 모두 선택적이며, 서버가 거부 시점에 해당 정보를 기록해둔 경우에만 나타납니다. 모르는 필드를 다루듯 필드가 없으면 그냥 무시하면 됩니다. 두 필드 모두 401에는 절대 포함되지 않습니다. 다만 인증되지 않은 호출자도 본문 자체는 받을 수 있습니다(DRF 기본 형식인 {"detail": "..."}). 단지 gate나 missing만 없을 뿐입니다. 그리고 모든 403이 아직 코드화된 것은 아닙니다. 일부 권한 검사는 여전히 같은 코드 없는 {"detail": "..."} 형식을 그대로 반환하며, 이 경우 code, gate, missing 모두 없습니다. gate나 missing을 읽기 전에 먼저 code가 있는지 확인하세요.

gate 값:

missing 값:

예시: 역할 거부

{
  "code": "rbac_permission_required",
  "gate": "role",
  "missing": "role"
}

예시: 토큰 스코프 부족

{
  "code": "api_token_scope_missing",
  "gate": "token_scope",
  "missing": "scope:server:update"
}

gate와 missing에는 규칙의 내용, 다른 사용자의 신원, 부족한 것을 요청할 수 있는 경로가 절대 담기지 않습니다. 제어의 종류와 전제 조건의 종류만 담깁니다. 이 응답 형식에서 모르는 필드를 만나면 참고 정보로만 여기고 무시해도 안전합니다.

Alpacon 주요 기능

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