API 설계
구현보다 먼저 계약을 설계하세요.
사용 시기
다음과 같은 경우에 사용하세요:
- 사용자가 새 API나 인터페이스를 설계할 때;
- 기존 계약을 변경할 때;
- 요청/응답 스키마를 정의할 때;
- 오류 처리, 인증, 페이지네이션 또는 버저닝을 검토할 때;
- 타사 서비스와 통합할 때;
- "이 엔드포인트는 어떻게 생겨야 하나요?"라고 물을 때.
1. 계약 명확화
다음을 식별하세요:
- API를 호출하는 주체: 프론트엔드, 모바일, 서비스, 파트너, 에이전트;
- 호출자가 달성해야 하는 작업;
- 입력 및 출력 데이터;
- 호출자가 절대 볼 수 없어야 하는 데이터;
- 지연 시간, 볼륨 및 안정성 요구 사항;
- 호환성 및 버저닝 제약 조건.
2. 리소스 및 액션 모델링
- 리소스에는 명사를 사용하고, CRUD가 아닌 작업에는 명시적인 액션을 사용하세요.
- URL을 안정적이고 예측 가능하게 유지하세요.
- 한 가지 작업을 수행하는 명확한 방법 하나를 선호하세요.
- 데이터베이스 구조를 공개 계약에 노출하지 마세요.
- 식별자, 소유권 및 테넌시를 정의하세요.
3. 스키마 정의
각 엔드포인트 또는 인터페이스에 대해:
- 메서드 및 경로;
- 목적;
- 인증 및 권한;
- 경로, 쿼리 및 본문 매개변수;
- 유효성 검사 규칙;
- 성공 응답;
- 오류 응답;
- 멱등성;
- 페이지네이션;
- 속도 제한;
- 예시.
4. 오류 설계
모든 오류는 다음을 포함해야 합니다:
- 안정적인 기계 판독 가능 코드;
- 사람이 읽을 수 있는 메시지;
- 원인이 된 필드 또는 매개변수;
- 지원을 위한 요청 ID;
- 스택 추적, 비밀 또는 내부 경로 없음.
일관된 HTTP 상태 코드를 사용하세요. 실패한 작업에 대해 200을 반환하지 마세요.
5. 보안 및 프라이버시
- 모든 비공개 엔드포인트를 인증하세요.
- 라우트 수준뿐만 아니라 객체 수준에서도 권한을 부여하세요.
- 모든 입력을 경계에서 검증하세요.
- 호출자에게 필요한 필드만 반환하세요.
- 내부 ID가 정보를 유출하는 경우 노출하지 마세요.
- 속도 제한 및 남용 방지 조치를 정의하세요.
- 웹훅을 신뢰할 수 없는 입력으로 취급하세요.
6. 진화성
- 필드의 의미를 변경하기보다는 필드를 추가하세요.
- 클라이언트가 마이그레이션할 때까지 이전 필드를 유지하세요.
- 필요한 경우에만 버저닝하세요.
- 지원 중단 및 마이그레이션을 문서화하세요.
- 부 버전에서 호환성이 깨지는 변경을 피하세요.
7. 출력 형식
## 계약
### `METHOD /path`
**목적:** <동작 설명>
**인증:** <호출 가능한 주체>
**멱등성:** <예/아니오 및 키>
#### 요청
| 필드 | 유형 | 필수 | 규칙 |
|---|---|---|---|
#### 응답
```json
{}
```
#### 오류
| 상태 | 코드 | 상황 |
|---|---|---|
#### 예시
```http
METHOD /path
...
```
## 호환성
- <변경 가능한 사항>
- <새 버전이 필요한 사항>
## 미해결 질문
- <질문>
규칙
- 비즈니스 규칙을 임의로 만들지 마세요.
- 이유 없이 내부 필드를 노출하지 마세요.
- 엔드포인트 간에 일관되지 않은 명명을 사용하지 마세요.
- 현재 데이터베이스 스키마를 기반으로 공개 API를 설계하지 마세요.
- 오류 및 빈 상태 동작을 생략하지 마세요.
- API가 금융, 의료 또는 개인 데이터를 처리하는 경우 보안 검토를 요구하세요.
품질 검사
- 호출자와 작업이 명확합니다.
- 스키마가 완전합니다.
- 오류가 일관되고 안전합니다.
- 인증 및 객체 수준 권한이 정의되어 있습니다.
- 페이지네이션 및 제한이 정의되어 있습니다.
- 호환성이 고려되었습니다.
- 예제가 유효합니다.