API 설계은(는) 무엇을 하나요?
좋은 API는 의존하는 사람들을 깨뜨리지 않고 발전시킬 수 있는 계약입니다. 계약을 먼저 설계하고, 동작보다 리소스를 모델링하며, HTTP를 명세에 맞게 사용하고, 하위 호환성을 유지하며, 보안과 운용성을 기본값(사후에 추가하는 것이 아님)으로 만드세요.
이 스킬은 워크플로우 수준에서 프로토콜에 구애받지 않습니다. 상세 정보는 references/에 있으며 필요 시 로드됩니다.
먼저 읽을 것(항상)
learnings/를 나열하고 현재 작업과 관련 있어 보이는 모든 파일을 읽으세요. 프로젝트의 버전 관리 정책, 오류 봉투(errors envelope), 인증 모델, 명명 규칙, 공급자별 웹훅 특이사항이 그곳에 있으며 이 파일의 기본값을 재정의합니다. 학습 내용이 이 SKILL.md와 충돌하면 학습 내용이 우선합니다. 사용자에게 이를 알리세요.
트레이드오프 — 적용 시점과 완화 시점
외부 또는 교차 팀 소비자가 있거나 상태를 유지하는 모든 API에는 전체 규율을 적용하세요. 양쪽을 완전히 제어하고 원자적으로 변경할 수 있는 단일 소비자 전용 프라이빗 엔드포인트의 경우 절차를 가볍게 할 수 있습니다. 단, 보안 기준(권한 부여, 입력 검증, URL에 시크릿 금지)은 절대 가볍게 하지 마세요.
워크플로우
-
프로토콜을 신중하게 선택하세요. REST는 리소스 CRUD와 광범위한 클라이언트 도달을 위해, GraphQL은 클라이언트가 유연하고 클라이언트 형태의 쿼리를 그래프에 대해 필요로 할 때, gRPC는 지연 시간이 짧은 내부 서비스 간 통신을 위해 사용합니다. 새롭다는 이유로 GraphQL/gRPC를 기본값으로 선택하지 마세요. 선택과 그 이유를 명시하세요. → 확인: 소비자를 지정하고 이 프로토콜이 적합한 이유를 말할 수 있어야 합니다.
-
계약 우선으로 설계하세요. 코드 전에 OpenAPI(또는 proto/SDL) 스펙을 작성하고, 검토한 후, 이에 대해 핸들러를 생성하거나 직접 작성하세요. CI에서 스펙을 린트하세요(예: Spectral). 변경으로 인해 빌드가 실패해야 합니다. → 확인: 스펙이 존재하고 진실의 원천(source of truth)이며, 코드에서 역설계된 것이 아니어야 합니다.
-
리소스(명사)를 모델링하고, 동작은 모델링하지 마세요. 리소스는 식별자를 가진 사물입니다. 컬렉션은 복수형입니다. 특이한 작업은 하위 리소스나 상태가 되며, 경로에 동사가 들어가지 않습니다.
references/rest-conventions.md를 참조하세요. → 확인: 어떤 경로에도 동사가 없어야 합니다. -
HTTP 메서드 + 상태 코드 의미론을 올바르게 사용하세요. GET/HEAD는 안전하고 멱등적이며, PUT/DELETE는 멱등적, PATCH는 부분적, POST는 생성/비멱등적입니다. 상태 코드는 결과를 전달하고, 본문은 데이터나 오류를 전달합니다.
references/rest-conventions.md를 참조하세요. → 확인: 본문에 오류가 있는200 OK가 없어야 합니다. -
모든 곳에 일관된 규칙을 적용하세요. 경로와 필드에 하나의 케이싱(casing), 복수형 컬렉션, 불투명 ID(DB 시퀀스/구조 유출 금지). 일관성 부족은 모든 소비자에게 영구적인 부담입니다. → 확인: 독자가 보지 않은 엔드포인트의 형태를 예측할 수 있어야 합니다.
-
소비자를 절대 깨뜨리지 마세요. 버전 내에서는 추가만 허용됩니다. 변경 사항이 하위 호환성을 깨뜨리면 새 버전과
Deprecation/Sunset헤더를 포함한 폐지 기간이 필요합니다. 이전에 페이지네이션이 없던 목록에 페이지네이션을 추가하는 것은 변경 사항을 깨뜨리는 것입니다.references/versioning-and-compatibility.md를 참조하세요. → 확인: 변경 사항을 배포하기 전에 모든 변경 사항이 추가적인지 또는 깨뜨리는지 분류합니다. -
오류를 표준화하세요. 안정적인 기계 판독 가능
code와 함께 RFC 9457application/problem+json을 사용하세요. HTTP 상태는 본문과 일치해야 합니다. 절대 스택 트레이스를 유출하지 마세요.references/errors-idempotency-concurrency.md를 참조하세요. → 확인: 모든 오류 경로가 동일한 봉투 형태와 안정적인 코드를 반환합니다. -
첫날부터 모든 목록을 페이지네이션하세요. 커서 기반(
page_size+page_token/next링크)이 오프셋보다 선호됩니다. 나중에 페이지네이션을 추가하면 클라이언트가 깨집니다. → 확인: 제한 없는 목록 엔드포인트가 없어야 합니다. -
쓰기 작업을 재시도해도 안전하게 만드세요. 비멱등적 POST에는
Idempotency-Key(첫 번째 응답을 저장하고 재생)를 사용하고,ETag+If-Match로 낙관적 동시성을 적용하여 충돌 시412를 반환합니다.references/errors-idempotency-concurrency.md를 참조하세요. → 확인: 타임아웃 후 POST를 재시도하는 클라이언트가 이중 청구/이중 생성을 할 수 없어야 합니다. -
기본 보안. TLS만 사용하고, 서버 측에서 토큰을 검증하며, 객체별 권한 부여(단순 역할 기반이 아님)를 수행하고, URL에 시크릿을 포함하지 않으며, 스키마에 대해 입력을 검증하고, 속도 제한을 적용하며, CORS 허용 목록을 사용합니다.
references/security.md를 참조하세요. → 확인: 객체 수준 권한 부여는 객체를 명명하는 모든 요청에서 확인됩니다. -
학습 내용 기록(마지막 단계). 이 파일이나
references/에 없는 규칙, 제약 조건, 함정을 발견했다면learnings/YYYY-MM-DD-slug.md를 추가하세요. 그렇지 않으면 건너뜁니다.
안티패턴(발견 즉시 거부)
- 경로에 동사 사용 —
POST /createUser,/getOrders.POST /users,GET /orders를 사용하세요. - 본문에 오류가 있는
200 OK. 상태 코드가 결과입니다. 클라이언트와 프록시가 이에 의존합니다. - 내부/DB 모델 유출 — 컬럼 이름, 내부 열거형, 시퀀스 ID, 조인 구조를 공개 형태로 노출하는 것. 의도적인 DTO에 매핑하세요.
- 수다스러운 엔드포인트 / N+1 — 클라이언트가 하나의 뷰를 구성하기 위해 여러 번의 왕복을 강제하는 경우. 확장(
expand=) 또는 더 큰 리소스를 제공하세요. - 새 버전 없이 하위 호환성을 깨뜨리는 변경 — 필드 이름 변경/제거, 유형 또는 기본값 변경, 또는 이전에 페이지네이션이 없던 목록에 페이지네이션 추가를 포함합니다.
- 일관성 없는 규칙 — 혼합된 케이싱, 단수형과 복수형 컬렉션, 때로는 래핑된 응답.
- 멱등성 키가 없는 비멱등적 POST — 재시도 시 이중 생성.
- URL의 민감한 데이터 — 경로 또는 쿼리에 토큰, PII, 시크릿이 포함되면 로그, 히스토리, 리퍼러에 기록됩니다.
- 객체 수준 권한 부여 누락(BOLA) — 인증은 확인하지만 이 호출자가 이 객체에 접근할 수 있는지 확인하지 않음. OWASP API #1.
- 스택 트레이스 노출 — 내부 클래스 이름, 파일 경로, SQL이 오류 본문에 포함됨.
- 제한 없는 목록 엔드포인트 —
GET /events가 모든 것을 반환.
학습 내용 기록
작업을 마치면 이 SKILL.md나 references/에 없는 규칙, 제약 조건, 함정을 만났는가? (프로젝트별 버전 관리 정책, 조직에서 표준화한 비표준 오류 봉투, 웹훅 제공자의 서명 체계, 필수 헤더)를 확인하세요. 그렇다면 learnings/README.md에 따라 learnings/YYYY-MM-DD-slug.md를 추가하세요. 아니면 생략하세요. 잡음을 만들지 마세요.
참고
references/rest-conventions.md— 리소스 모델링, 명명, 메서드, 상태 코드, 페이지네이션, 필터링, 캐싱.references/versioning-and-compatibility.md— 버전 관리 전략, 추가 vs 변경 사항, 폐지 정책.references/errors-idempotency-concurrency.md— problem+json, 멱등성 키, 낙관적 동시성, 재시도, 장기 실행 작업, 웹훅.references/security.md— TLS, OAuth2/OIDC, BOLA/BFLA, 입력 검증, 속도 제한, CORS, 데이터 노출.developing-features스킬 — 일반 프로덕션 규칙 및 전체 보안 참조(API 표면은 여러 경계 중 하나).reviewing-code스킬 — API 표면을 변경하는 diff 검토.documenting-features스킬 — 코드와 함께 API 계약, ADR, 도메인 모델 캡처.learnings/— 시간이 지남에 따라 축적된 프로젝트별 API 규칙.