Boundary API 개요

Boundary의 API는 엄격하게 지켜지는 표준을 따르는 JSON 기반 HTTP API예요. 핵심적으로 입력과 출력 모두 표준을 준수하는 JSON API죠.

출처: HashiCorp Boundary docs

본문

이 페이지를 읽기 전에 Boundary의 도메인 모델을 이해해 두면 여기서 쓰는 용어를 파악하기 쉬워요.

Boundary의 API는 OpenAPI v2로도 설명돼요. Boundary 소스 코드의 특정 태그에 해당하는 버전은 Boundary의 GitHub 리포지토리에서 찾을 수 있어요.

참고: 생성된 API 정의의 렌더링된 버전은 API 페이지를 참고해요.

Boundary의 현재 API 버전은 1이고, 모든 API 경로는 /v1/로 시작해요.

상태 코드 (Status codes)

2XX: 성공 시 Boundary는 200~299 사이의 코드를 반환해요. 대개 200이지만, 구현체는 어떤 2XX 상태 코드든 성공으로 받아들이도록 준비해야 해요. 200이 아닌 2XX 코드가 반환되면 해당 상태 코드의 이미 잘 알려진 의미를 따르도록 돼 있어요. 삭제 작업은 성공 시 204를 반환해요.
400: 유효하지 않은 사용자 입력 때문에 명령을 완료할 수 없을 때 Boundary는 400을 반환해요. 단, 형식이 올바른 식별자지만 존재하는 리소스에 매핑되지 않는 경우는 아래 설명처럼 404를 반환해요.
401: 인증 토큰이 제공되지 않았거나 제공된 토큰이 유효하지 않으면 Boundary는 401을 반환해요. 단순히 리소스에 대한 권한이 없는 유효한 토큰은 대신 403을 반환해요. 토큰이 유효하지 않거나 없지만, 익명 사용자(u_anon)가 그 작업을 성공적으로 수행할 수 있는 경우에는 401 대신 그 작업의 결과를 반환해요.
403: 제공된 토큰이 유효하지만 요청한 작업을 수행하는 데 필요한 그랜트가 없으면 Boundary는 403을 반환해요.
404: 리소스를 찾을 수 없으면 Boundary는 404를 반환해요. 거의 모든 경우 이는 인증/인가 확인보다 먼저 일어나는데, 리소스 정보(스코프, 가능한 작업 등)가 그 확인의 필수 부분이기 때문이에요. 그 결과 존재하지 않는 리소스에 대한 작업은 401이나 403 대신 404를 반환해요. 이는 정보 유출로 볼 수도 있지만, ID는 무작위로 생성되고 이는 단지 ID가 유효한지 여부만 드러내므로, 훨씬 단순하고 견고한 클라이언트 구현을 가능하게 해주는 점에서 허용 가능해요.
405: 주어진 리소스에 대해 메서드(HTTP 동사 또는 사용자 지정 작업)가 구현되지 않았음을 나타내기 위해 Boundary는 405를 반환해요.
429: 리소스와 액션에 대한 API 속도 제한 할당량(quota)이 소진되면 Boundary는 429를 반환해요. 클라이언트가 새 요청을 하기 전에 얼마나 기다려야 하는지 알 수 있도록 Retry-After 헤더를 포함해요.
500: 유효하지 않은 사용자 입력과 (직접적으로) 관련되지 않은 오류가 발생하면 Boundary는 500을 반환해요. 500이 생성되면 오류에 대한 정보가 Boundary 서버 로그에 기록되지만 일반적으로 클라이언트에는 제공되지 않아요.
503: API 속도 제한 초과로 할당량을 저장할 수 없으면 Boundary는 503을 반환해요. 클라이언트가 새 요청을 하기 전에 얼마나 기다려야 하는지 알 수 있도록 Retry-After 헤더를 포함해요.

경로 레이아웃 (Path layout)

Boundary는 예측 가능한 경로 레이아웃을 따라요. 각각 다른 작업 집합을 지원하는 두 가지 기본 유형의 URL 경로가 있어요.

컬렉션 (Collections)

리소스 컬렉션은 리소스의 복수 영어 이름을 가진 최상위 경로예요. 예를 들어 /roles와 /hosts가 있죠. 컬렉션은 다음 작업을 지원해요.

해당 컬렉션 안에 새 리소스 생성
해당 컬렉션 안의 리소스 나열

모든 컬렉션 작업은 포함하는 리소스(enclosing resource)를 제공해야 해요. 컬렉션 유형에 따라 다음 중 하나가 될 수 있어요.

스코프: 작업이 일어나야 할 스코프를 나타내요. 예를 들어 /roles에 대한 POST는 역할이 global 스코프에 만들어질지 o_1234567890 같은 org 수준 스코프에 만들어질지를 표시해야 해요.
적절한 유형의 부모 리소스. 예를 들어 호스트와 호스트 집합은 호스트 카탈로그의 자식 리소스예요. 호스트 카탈로그 안에 새 호스트 집합을 만들 때 /host-sets에 대한 POST는 그 호스트 집합이 연결되어야 할 호스트 카탈로그 ID를 표시해야 해요.

리소스 (Resources)

리소스 자체는 컬렉션 경로 안의 ID 지정자로 정의돼요. 예를 들어 /roles/r_1234567890이죠. 리소스는 다음 작업을 지원해요.

리소스 속성 읽기
리소스 속성 업데이트
리소스 삭제
리소스 유형에 특화된 사용자 지정 메서드

리소스 유형에 따라 다양한 파라미터가 가능할 수 있어요. 일부는 모든 리소스 유형에 공통적이고(예: name, description), 다른 것들은 특정 유형에서만 사용 가능해요. 또한 추상 리소스의 일부 구체 유형은 유형별 값을 가진 불투명한 attributes JSON 객체를 포함해요.

예를 들어 인증 메서드(auth method)는 추상 유형이고, 비밀번호 인증 메서드는 그 유형의 구체적인 구현이에요. 이런 인증 메서드를 만들 때 type 파라미터가 비밀번호 유형임을 나타내고, 최소 비밀번호 길이 같은 비밀번호 유형 인증 메서드에 특화된 값은 attributes 객체 안에 담겨요.

메서드 (Methods)

Boundary의 API에서 사용되는 메서드 규칙은 다음과 같아요.

GET

GET은 리소스를 읽거나 컬렉션의 리소스를 나열하는 데 사용해요. 동작은 GET이 컬렉션(/roles)에 대해 발행됐는지 단일 리소스(/roles/r_1234567890)에 대해 발행됐는지에 따라 달라져요. 전자의 경우 컬렉션 안의 리소스를 나열하고, 후자의 경우 해당 특정 리소스에 대한 읽기를 수행해요.

POST

POST는 리소스를 만들거나 리소스에 대한 사용자 지정 작업을 수행하는 데 사용해요. 리소스를 만들 때는 컬렉션(/roles)에 POST를 사용해요. 사용자 지정 작업을 수행할 때는 특정 리소스(/roles/r_1234567890:set-principals)에 POST를 사용해요.

PATCH

PATCH는 리소스의 파라미터를 업데이트하는 데 사용해요. PATCH를 사용할 때 알아둬야 할 동작은 다음과 같아요.

거의 모든 경우 version 파라미터가 필요해요. 이는 check-and-set에 사용되어 업데이트 작업이 알려진 리소스에 대해 수행되는지 보장해요. version 파라미터는 리소스에 대한 GET 작업에서 반환되므로, 현재 버전을 리소스의 다른 현재 값과 함께 언제든 조회할 수 있어요.
파라미터에 JSON null을 전달하면 그 파라미터를 기본값으로 되돌리는 효과가 있어요. 일부 파라미터(예: name)에서는 단순히 값을 비우고(리소스의 기본 이름은 비어 있으므로), 다른 파라미터에서는 Boundary의 현재 기본값으로 되돌려요.
PATCH 작업의 일부로 지정된 모든 파라미터는 업데이트되어야 하는 파라미터로 간주돼요.

DELETE

DELETE는 특정 리소스를 삭제하는 데 사용하며, 특정 리소스 경로에만 사용해요.

HTTP 헤더 (HTTP headers)

컨트롤러 API에 요청하는 클라이언트는 HTTP 응답 헤더를 검사해서 설정된 한도와 현재 사용량을 이해할 수 있어요. 응답에는 다음 헤더가 포함될 수 있어요.

RateLimit — 요청한 리소스와 액션에 대해 소진에 가장 가까운 한도의 현재 한도, 남은 요청 수, 할당량이 재설정되는 시각을 제공해요.
RateLimit-Policy — 요청한 리소스와 액션의 한도를 설명해요.
X-Correlation-ID — 일련의 요청과 응답에 걸쳐 트랜잭션을 식별해요. X-Correlation-ID 헤더는 범용 고유 식별자(UUIDv4)예요. HTTP 요청에 X-Correlation-ID 헤더를 제공하면 Boundary가 그 요청과 관련된 모든 감사 이벤트에 그 값을 기록해요. 그리고 Vault 같은 외부 시스템에 관련 요청을 할 때 그 값을 헤더로 사용해서 제품 로그 간 이벤트를 연관 지을 수 있어요. X-Correlation-ID 헤더를 제공하지 않으면 Boundary는 들어오는 각 요청에 고유한 값을 생성해요.

시스템 리소스 관리 (Manage system resources)

컨트롤러가 모든 API 요청을 처리하려 하면 리소스가 고갈되거나 데이터베이스 서버가 과부하될 수 있어요. Boundary는 너무 많은 동시 요청으로 시스템 리소스가 압도당하는 것을 막기 위해 API 속도 제한(rate limiting) 기능을 제공해요. 자세한 내용은 API 속도 제한을 참고해요.

또한 list 작업으로 Boundary 리소스를 검색하면 매우 많은 결과를 받을 수도 있어요. Boundary는 API 페이지네이션 기능을 사용해 시스템 리소스를 압도하지 않으면서 큰 목록을 검색하고 필터링할 수 있게 해줘요. 페이지네이션과 검색에 로컬 캐시를 사용하는 방법에 대해서는 API 목록 페이지네이션을 참고해요.

Boundary API 개요