API 문서

Alpacon은 서버의 상태를 제어하고 관리할 수 있는 RESTful API를 제공합니다. API의 루트 엔드포인트는 /api/이며, 웹 브라우저를 통해 https://alpacon.io/api/에 접속할 수 있습니다. 계정으로 로그인하면 사용 가능한 모든 API 목록을 확인할 수 있습니다.

API 엔드포인트

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

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

여기서:

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

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

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

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

전역 정보

HTTP 메서드

Alpacon의 REST API는 다음과 같은 표준 HTTP 메서드를 지원합니다:

  • GET: 리소스 목록 조회 또는 단일 조회
  • POST: 리소스 생성
  • PUT: 리소스 전체 수정
  • PATCH: 리소스 일부 수정
  • DELETE: 리소스 삭제

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

상태 코드

API 요청이 성공했을 때 일반적으로 다음과 같은 상태 코드가 반환됩니다:

  • 200 OK: 요청이 성공했습니다. (GET, PUT, PATCH)
  • 201 CREATED: 리소스가 생성되었습니다. (POST)
  • 204 NO CONTENT: 리소스가 삭제되었습니다. (DELETE)

요청이 실패한 경우에는 다음과 같은 상태 코드가 반환될 수 있습니다:

  • 400 Bad Request: 요청 데이터에 문제가 있어 잘못된 요청입니다. 응답에는 에러 메시지가 포함되어 있으며, 클라이언트는 이를 파싱하여 사용자에게 안내해야 합니다.
  • 401 Unauthorized: 인증되지 않았거나 인증 정보가 부족한 경우입니다. 인증 정보를 포함한 요청을 다시 보내야 합니다.
  • 403 Forbidden: 인증은 되었지만 해당 작업에 대한 권한이 없는 경우입니다. 클라이언트는 /api/auth/is-authenticated/를 통해 인증 여부를 확인할 수 있으며, 인증된 사용자라도 요청이 거부될 경우 403 에러 페이지로 리다이렉트할 수 있습니다.
  • 404 Not Found: 요청한 리소스가 존재하지 않습니다. 클라이언트는 404 페이지로 리다이렉트할 수 있습니다.
  • 405 Method Not Allowed: 허용되지 않은 HTTP 메서드입니다. 이는 개발 단계에서 처리되어야 하며, 최종 사용자에게는 노출되지 않아야 합니다.
  • 500 Server Error: 서버 내부 오류입니다. 클라이언트는 사용자에게 500 에러 페이지를 보여줄 수 있습니다.

에러 메시지

앞서 언급한 바와 같이, 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 컬렉션에 대한 세부 정보를 제공합니다.

인증(Authentication)
명령어
IAM (신원 및 접근 관리)
서버 관리
Websh