API

API가 기록하는 정보#

API는 Endpoint를 묶는 공개·내부 인터페이스입니다. 이름은 Organization 안에서 고유합니다.

등록 방법은 첫 Catalog 기록을 참고합니다.

Base URL#

base_urls의 각 항목은 url과 선택 label(최대 60자)을 받습니다.

{
  "name": "Orders API",
  "handle": "orders-api",
  "base_urls": [
    {"url": "https://api.example.com/orders", "label": "운영"},
    {"url": "https://staging-api.example.com/orders", "label": "스테이징"}
  ]
}

• url은 http·https 절대 URL입니다. query·fragment·사용자 정보·{region} 같은 템플릿 변수는 받지 않으므로 실제 값으로 펼쳐 적습니다.
• 서버는 주소를 정규화해 입력 순서대로 저장하며 그 주소에 접속하지 않습니다. 정규화 후 같은 주소가 겹치면 거부합니다.
• 수정할 때 base_urls를 생략하면 저장된 목록을 유지하고, []를 보내면 모두 지웁니다.

Endpoint 상세는 소속 API의 Base URL 목록을 함께 표시합니다.

제공 Service#

API를 제공하는 Service를 하나 지정하거나 비워 둡니다. Endpoint의 제공 Service는 소속 API를 따릅니다. Web UI에서는 API 상세의 제공 Service에서 제공 Service 변경으로 Service 또는 제공 Service 없음을 고릅니다.

stly apis service get <api-id>
stly apis set-service <api-id> --service <service-id> --if-match '"제공 Service 조회의 ETag"'
stly apis set-service <api-id> --none --if-match '"제공 Service 조회의 ETag"'

제공 Service의 ETag는 API 자체의 ETag와 다릅니다. apis service get의 etag를 사용하며 오래된 ETag는 HTTP 412입니다.

OpenAPI 문서#

OpenAPI 문서 하나는 API 하나와 연결합니다. Repository 없는 문서는 API 상세의 OpenAPI 문서에 표시되며 새 원문 제출과 structly.yaml 내려받기를 엽니다. 등록·반영 방법은 OpenAPI 동기화를 참고합니다.

Endpoint와 System#

stly endpoints list --api <api-id> --fields id,method,path
stly apis systems <api-id>

Endpoint는 Endpoint에서, System 구성은 System에서 기록합니다.

삭제#

소속 Endpoint가 남아 있으면 API를 삭제할 수 없습니다(HTTP 409 API_IN_USE). Endpoint를 다른 API로 옮기거나 삭제한 뒤 삭제합니다. 제공 Service와 연결 OpenAPI 문서는 삭제를 막지 않으며, 연결 문서는 남고 API 연결만 해제됩니다.

인증 Metadata#

API 상세에서 인증 방식 정의와 공통 요구사항을 편집합니다. API key·HTTP·mutual TLS·OAuth·OpenID Connect의 공개 설정을 기록하며 토큰·비밀번호 등 자격 증명은 입력하지 않습니다. 아래 security 필드를 API 생성·전체 수정 JSON에 함께 넣습니다.

{"security":{"schemes":{"token":{"type":"http","scheme":"bearer"}},"requirements":[{"token":[]}]}}

requirements: null은 공통 선언 없음, []는 명시적 요구 없음입니다. 배열 항목은 OR, 같은 항목 안의 방식은 AND이며 {} 항목은 익명 대안입니다. OAuth·OIDC의 값은 Scope이고 다른 방식의 값은 역할 이름입니다. 실제 서버의 인증을 검증한 결과는 아닙니다.

이름을 참조하는 Endpoint가 남아 있으면 정의를 제거할 수 없습니다. 수정에서 security 생략은 보존이고 객체를 보내면 전체 교체합니다. stly apis validate --operation create 또는 update <api-id> --if-match ...로 저장 전에 입력을 검사할 수 있습니다. 공통 CLI 입력 규칙을 따릅니다.