Catalog 가이드

Endpoint

이 페이지의 내용

Endpoint가 기록하는 정보#

필드	내용
`method`·`path`	HTTP Method와 라우트 템플릿(예: `/orders/{order_id}`). 필수
`api_id`	소속 API. 선택이며 생략하면 소속 없이 저장합니다
`summary`·`description`	한 줄 요약과 설명
`deprecated`	사용 중단 예정 선언. 생략하면 false
`parameters`	Path·Query Parameter와 Schema
`headers`	요청·응답 Header와 Schema
`request_body`	Media Type별 요청 본문 Schema
`responses`	Status별 응답과 Media Type별 Schema
`examples`	요청·응답 시나리오 예제
`external_references`	코드·외부 문서 출처

Schema는 JSON Schema 2020-12로 적습니다. method는 GET·HEAD·POST·PUT·DELETE·OPTIONS·PATCH·TRACE를 받습니다.

Web UI#

Endpoints → 새 Endpoint에서 입력하고 Endpoint 등록을 누릅니다. 상세에서 소속 API의 Base URL과 이 Endpoint를 호출하는 Workflow를 함께 확인합니다.

Endpoint·Parameter·Header는 각자의 deprecated를 기록합니다. 목록·상세의 사용 중단 예정 표시는 다른 위치로 전파되지 않으며 필수 여부를 바꾸지 않습니다. Schema의 같은 키는 해당 Schema의 annotation입니다. 수정 JSON에서 deprecated를 생략하면 기존 true도 false로 교체하므로 유지할 값은 함께 제출합니다.

stly#

endpoint.json 예입니다. Path의 {order_id}마다 같은 이름의 Path Parameter가 필요하며 Path Parameter는 required: true입니다.

{
  "api_id": "4pkKFh2ojXs",
  "method": "GET",
  "path": "/orders/{order_id}",
  "summary": "주문 상세 조회",
  "parameters": [
    {"name": "order_id", "location": "path", "required": true, "schema_definition": {"type": "string", "format": "uuid"}}
  ],
  "responses": [
    {"status_key": "200", "description": "주문", "contents": [
      {"media_type": "application/json", "schema_definition": {"type": "object", "required": ["id", "status"], "properties": {"id": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "paid", "cancelled"]}}}}
    ]},
    {"status_key": "404", "description": "주문 없음"}
  ],
  "examples": [
    {"name": "결제 완료 주문",
     "request_example": {"path_parameters": [{"name": "order_id", "value": "50ECYsM55Ec"}]},
     "response_example": {"status_code": 200, "body": {"media_type": "application/json", "value": {"id": "50ECYsM55Ec", "status": "paid"}}}}
  ]
}

저장 전에 서버에서 검사한 뒤 생성합니다.

stly endpoints validate --operation create --input endpoint.json
stly endpoints create --input endpoint.json
stly endpoints list --api 4pkKFh2ojXs --fields id,method,path,summary

endpoints list --q는 Path·요약·설명에서 대소문자를 구분해 찾습니다.

예제#

examples의 각 항목은 이름과 요청 예제·응답 예제 한 쌍입니다.

요청 예제는 path_parameters·query_parameters·headers·body를 담습니다.
응답 예제는 구체적인 정수 status_code와 headers·body를 담습니다.
body는 {"media_type": "...", "value": ...} 형식입니다. 본문이 없으면 body를 생략합니다.
오류 응답 예제도 기록할 수 있으며, 예제가 Schema에 맞는지는 검사하지 않습니다.

External Reference#

코드·외부 문서의 출처를 external_references에 기록합니다. url과 external_id 중 하나 이상이 필요합니다.

{"external_references": [{"label": "코드 출처", "url": "https://github.com/acme/orders-service/blob/3f2c1a9/src/routes/orders.ts#L10", "external_id": ""}]}

commit SHA로 고정한 URL을 권장합니다. 수정할 때 생략하면 저장된 값을 유지하고 []이면 모두 지웁니다.

호출 Workflow#

stly endpoints workflows <endpoint-id>

이 Endpoint를 Step에서 호출하는 Workflow를 반환합니다. Workflow는 Workflow에서 기록합니다.

스펙 출처가 있는 Endpoint#

OpenAPI 동기화로 만든 Endpoint는 Web UI에 스펙 출처와 출처 문서 링크를 표시합니다. Method·Path·요청·응답을 포함한 필드를 직접 수정할 수 있으며, 다음 계획에서 원문과 다른 값은 변경으로 보고됩니다. API 소속은 출처 문서의 API를 따르므로 바꿀 수 없습니다(HTTP 409 ENDPOINT_SPEC_MANAGED). 다른 API로 옮기려면 출처를 먼저 해제합니다.

Endpoint 목록의 API 제공 Service 열은 소속 API의 제공 Service를 표시합니다.

삭제#

Workflow의 Step이 호출하는 Endpoint는 삭제할 수 없습니다(HTTP 409 ENDPOINT_IN_USE). stly endpoints workflows로 호출하는 Workflow를 확인해 Step을 먼저 바꿉니다.

인증 선언과 적용 결과#

Endpoint의 security는 null이면 API 공통 선언을 상속하고 배열이면 재정의합니다. []는 명시적 요구 없음, [{}]는 익명 대안입니다. 이름 있는 방식은 연결 API의 인증 정의를 사용하므로 API 연결이 필요합니다. 수정에서 생략하면 저장한 선언을 유지합니다.

stly endpoints security <endpoint-id>

적용 조회는 선언 원천·요구사항·참조한 방식 정의를 반환합니다. 미선언은 실제 인증 불필요를 뜻하지 않습니다. 적용 조회 ETag는 Endpoint 수정용 ETag와 다릅니다.

Web 편집에서 API 이동·해제 전후의 적용 인증을 확인합니다. 상속은 대상 API를 따르고, 미연결로 바꾸면 선언 없음이 됩니다. 개별 재정의의 이름 참조는 대상 API에서 유효해야 하며 미연결로 바꾸려면 참조를 함께 정리합니다. 스펙 출처만 해제하면 인증 선언과 API 소속은 유지됩니다.