API 레퍼런스

API

이 페이지의 내용

이 페이지는 공개 계약에서 생성하며 설명은 원문(한국어) 그대로 표시합니다.

API Metadata와 호출 기준 Base URL 목록.

API 생성 후보 검증#

POST /api/apis/validate

실제 저장과 같은 검증·조건을 적용하되 저장 결과는 남기지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

UTF-8 JSON 객체 하나, 최대 4 MiB. 중복 키·복수 JSON 값·미정의 필드·서버 필드를 거부합니다.

타입: CreateAPIRequest

이름	타입	필수	설명
`handle`	`string`	예	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURLInput[]`	아니요	호출 기준 주소 목록. 생략하면 빈 목록입니다. 입력 순서를 보존하고 정규화 후 같은 주소의 중복은 422 duplicate_url입니다.
`security`	`SecurityDeclaration`	아니요

응답

상태	설명
`200`	검증 성공. 저장 없음
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`409`	PostgreSQL lower(name) UNIQUE 기준 이름 중복. 동시 쓰기도 덮어쓰지 않습니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	요청 본문이 64 KiB (65536 bytes)를 초과합니다.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필수 필드 누락·null·타입·이름·요약·설명 길이·문자 규칙 위반과 Base URL 목록의 항목 수(invalid_length)·URL 형식(invalid_value)·정규화 후 중복(duplicate_url)·label 규칙 위반. 전체 쓰기·시각 변경을 거부합니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: object

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `create`

API 수정 후보 검증#

PUT /api/apis/{id}/validate

실제 저장과 같은 검증·조건을 적용하되 저장 결과는 남기지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대소문자를 구분하는 불변 ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	대상 상세 GET의 단일 강한 ETag 필수. 관계 쓰기는 관계 ETag만 사용. 일반 검사 뒤 누락 428·불일치 412. *, 약한·복수 태그·잘못된 구문은 400. 미존재·삭제 참조 검사는 조건 평가보다 우선합니다.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

UTF-8 JSON 객체 하나, 최대 4 MiB. 중복 키·복수 JSON 값·미정의 필드·서버 필드를 거부합니다.

타입: ReplaceAPIRequest

이름	타입	필수	설명
`handle`	`string`	아니요	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURLInput[]`	아니요	호출 기준 주소 목록 전체 교체. 생략하면 같은 트랜잭션에서 잠근 기존 목록을 보존하고 `[]`는 전체 해제입니다.
`security`	`SecurityDeclaration`	아니요

응답

상태	설명
`200`	검증 성공. 저장 없음
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	ID 형식은 유효하지만 API가 없거나 이미 삭제되었습니다.
`409`	PostgreSQL lower(name) UNIQUE 기준 이름 중복. 동시 쓰기도 덮어쓰지 않습니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	최신 API를 다시 조회하고 변경·삭제 여부를 검토해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다.
`413`	요청 본문이 64 KiB (65536 bytes)를 초과합니다.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필수 필드 누락·null·타입·이름·요약·설명 길이·문자 규칙 위반과 Base URL 목록의 항목 수(invalid_length)·URL 형식(invalid_value)·정규화 후 중복(duplicate_url)·label 규칙 위반. 전체 쓰기·시각 변경을 거부합니다.
`428`	상세 GET의 ETag를 If-Match에 전달해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다. 날짜 조건만으로 대체할 수 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: object

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `update`

API 목록 조회#

GET /api/apis

본문은 받지 않습니다. q·sort·page·per_page를 모두 생략하면 envelope 없이 전체 API 객체 배열을 고정 순서로 반환합니다. page·per_page 중 하나라도 있으면 페이지 모드로 동작하고 X-Pagination-* 헤더를 반환합니다. 빈 목록·범위를 벗어난 페이지는 []입니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`handle`	query	`string`	아니요	handle 정확 일치 필터. 앞뒤 공백 제거·소문자 정규화 후 비교하며 형식이 맞지 않으면 400 INVALID_REQUEST입니다. 기존 q·sort·page·per_page와 함께 사용할 수 있습니다. 결과는 최대 1건입니다.
`q`	query	`string`	아니요	name·summary·description 중 하나에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. 값: `name`, `-name`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.

응답

상태	설명
`200`	목록. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다.
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

배열(API[])이며 표는 항목의 필드입니다.

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURL[]`	예	API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`security`	`SecurityDeclaration`	예

API 생성#

POST /api/apis

Description 생략은 빈 문자열. 서버가 ID·시각을 생성하고 생성 시 두 시각은 같습니다. 재전송은 새 생성 시도이며 고정 ID·Idempotency-Key·upsert를 제공하지 않습니다. 응답을 잃었으면 목록으로 저장 여부를 확인합니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

UTF-8 JSON 객체 하나, 최대 4 MiB. 중복 키·복수 JSON 값·미정의 필드·서버 필드를 거부합니다.

타입: CreateAPIRequest

이름	타입	필수	설명
`handle`	`string`	예	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURLInput[]`	아니요	호출 기준 주소 목록. 생략하면 빈 목록입니다. 입력 순서를 보존하고 정규화 후 같은 주소의 중복은 422 duplicate_url입니다.
`security`	`SecurityDeclaration`	아니요

응답

상태	설명
`201`	API 생성.
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`409`	PostgreSQL lower(name) UNIQUE 기준 이름 중복. 동시 쓰기도 덮어쓰지 않습니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	요청 본문이 64 KiB (65536 bytes)를 초과합니다.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필수 필드 누락·null·타입·이름·요약·설명 길이·문자 규칙 위반과 Base URL 목록의 항목 수(invalid_length)·URL 형식(invalid_value)·정규화 후 중복(duplicate_url)·label 규칙 위반. 전체 쓰기·시각 변경을 거부합니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

201 응답 본문

타입: API

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURL[]`	예	API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`security`	`SecurityDeclaration`	예

API 상세 조회#

GET /api/apis/{id}

본문·query parameter를 받지 않습니다. 소속 Endpoint를 중첩하지 않습니다. 강한 ETag를 반환하며 수정·삭제에 그대로 전달합니다. If-None-Match를 약한 비교로 평가해 일치는 304·본문 없음, 불일치는 200. 200·304에는 필수 ETag를 반환합니다. 미존재 404는 조건 평가에 우선하며 잘못된 헤더 형식은 400입니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대소문자를 구분하는 불변 ID. 잘못된 형식은 400 INVALID_ID.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	API 상세.
`304`	If-None-Match가 현재 ETag와 약한 비교로 일치하거나 *이고 항목이 존재함. 본문·Content-Type 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	ID 형식은 유효하지만 API가 없거나 이미 삭제되었습니다.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: API

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURL[]`	예	API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`security`	`SecurityDeclaration`	예

API 전체 수정#

PUT /api/apis/{id}

Name·Summary·Description 전체 교체이며 base_urls는 생략 시 기존 목록을 보존하고 []로 해제합니다. PATCH·upsert를 제공하지 않습니다. ID·created_at·소속 Endpoint는 유지합니다. 상세 GET의 ETag를 If-Match에 전달하며 버전 비교와 저장은 원자적입니다. 성공할 때마다 같은 값이어도 시각과 버전을 갱신합니다. 누락은 428, 불일치는 412이며 실패 시 값·시각을 유지합니다. 자동 병합하지 않습니다. PUT 응답에는 ETag를 제공하지 않으므로 상세 GET으로 새 토큰을 받습니다. If-Match와 함께 받은 If-Unmodified-Since는 무시합니다. 일반 검사에서 미존재 404를 먼저 처리하고 DELETE는 사전 소속 검사에서 삭제 불가 409를 먼저 처리합니다. 이후 If-Match 누락 428·불일치 412를 평가합니다. 날짜 조건만으로 쓰기를 허용하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대소문자를 구분하는 불변 ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	상세 GET의 강한 ETag 하나. *·약한 태그·복수 태그는 400. 일반 검사 통과 후 누락은 428, 불일치는 412. If-Match가 있으면 If-Unmodified-Since는 무시합니다. 미존재 404와 사전 소속 검사에서 확인한 삭제 불가 409는 누락·불일치보다 우선합니다.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

UTF-8 JSON 객체 하나, 최대 4 MiB. 중복 키·복수 JSON 값·미정의 필드·서버 필드를 거부합니다.

타입: ReplaceAPIRequest

이름	타입	필수	설명
`handle`	`string`	아니요	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURLInput[]`	아니요	호출 기준 주소 목록 전체 교체. 생략하면 같은 트랜잭션에서 잠근 기존 목록을 보존하고 `[]`는 전체 해제입니다.
`security`	`SecurityDeclaration`	아니요

응답

상태	설명
`200`	저장한 API.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	ID 형식은 유효하지만 API가 없거나 이미 삭제되었습니다.
`409`	PostgreSQL lower(name) UNIQUE 기준 이름 중복. 동시 쓰기도 덮어쓰지 않습니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	최신 API를 다시 조회하고 변경·삭제 여부를 검토해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다.
`413`	요청 본문이 64 KiB (65536 bytes)를 초과합니다.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필수 필드 누락·null·타입·이름·요약·설명 길이·문자 규칙 위반과 Base URL 목록의 항목 수(invalid_length)·URL 형식(invalid_value)·정규화 후 중복(duplicate_url)·label 규칙 위반. 전체 쓰기·시각 변경을 거부합니다.
`428`	상세 GET의 ETag를 If-Match에 전달해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다. 날짜 조건만으로 대체할 수 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: API

이름	타입	필수	설명
`id`	`string`	예	서버 생성·불변 ID.
`handle`	`string`	예	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	예	앞뒤 U+0020 공백을 제거한 저장 이름. 제어문자는 허용하지 않습니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`base_urls`	`BaseURL[]`	예	API 소유 호출 기준 주소 목록. 저장 순서를 그대로 반환하며 정규화 후 같은 주소는 한 번만 있습니다. 주소가 없으면 빈 배열입니다. 소속 Endpoint는 이 목록을 공통으로 사용합니다.
`created_at`	`string(date-time)`	예	생성 후 불변. 생성 시 updated_at과 같은 값.
`updated_at`	`string(date-time)`	예	같은 값의 PUT도 성공하면 새 서버 시각을 기록합니다.
`security`	`SecurityDeclaration`	예

API 삭제#

DELETE /api/apis/{id}

본문·query를 받지 않습니다. 상세 GET의 ETag를 If-Match에 전달하며 버전 비교와 삭제는 원자적입니다. 누락은 428, 불일치는 412이며 삭제·시각 변경을 하지 않습니다. 소속 Endpoint가 있으면 409로 거부합니다. 소속 재배정·해제는 허용하되 별도 Endpoint 계약으로 설계합니다. 참조 경쟁은 DB FK로 보증합니다. If-Match와 함께 받은 If-Unmodified-Since는 무시합니다. 일반 검사에서 미존재 404를 먼저 처리하고 DELETE는 사전 소속 검사에서 삭제 불가 409를 먼저 처리합니다. 이후 If-Match 누락 428·불일치 412를 평가합니다. 날짜 조건만으로 쓰기를 허용하지 않습니다. 사전 검사 통과 후 FK 경쟁 실패도 409 API_IN_USE로 변환하고 전체 롤백합니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대소문자를 구분하는 불변 ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	상세 GET의 강한 ETag 하나. *·약한 태그·복수 태그는 400. 일반 검사 통과 후 누락은 428, 불일치는 412. If-Match가 있으면 If-Unmodified-Since는 무시합니다. 미존재 404와 사전 소속 검사에서 확인한 삭제 불가 409는 누락·불일치보다 우선합니다.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

응답

상태	설명
`204`	삭제 성공. 본문·Content-Type 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	ID 형식은 유효하지만 API가 없거나 이미 삭제되었습니다.
`409`	소속 Endpoint가 있어 삭제를 거부합니다. API·Endpoint·시각을 유지하며 연쇄 삭제·자동 소속 해제를 하지 않습니다. 사전 소속 검사에서 확인하면 조회 버전 누락·불일치보다 우선합니다. 최종 FK 경쟁 실패도 같은 오류로 반환합니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	최신 API를 다시 조회하고 변경·삭제 여부를 검토해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다.
`428`	상세 GET의 ETag를 If-Match에 전달해 주세요. 일반 검사에서 미존재 404·사전 삭제 불가 409가 없을 때 반환합니다. 날짜 조건만으로 대체할 수 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.