API 설계발행일 2026. 8. 28.
리소스 중심 REST API 설계
동사 대신 리소스로 URL을 설계하고 일관된 상태 코드와 오류 응답을 정의합니다.
#REST#API#HTTP
URL은 리소스를 표현한다#
작업 이름보다 다루는 대상을 URL에 배치합니다.
| 목적 | 메서드 | URL |
|---|---|---|
| 글 목록 조회 | GET | /articles |
| 글 하나 조회 | GET | /articles/{slug} |
| 글 생성 | POST | /articles |
| 글 수정 | PATCH | /articles/{slug} |
오류 응답 규격#
클라이언트가 문자열을 해석하지 않도록 안정적인 오류 코드를 제공합니다.
{
"error": {
"code": "ARTICLE_NOT_FOUND",
"message": "요청한 문서를 찾을 수 없습니다.",
"requestId": "req_01J..."
}
}멱등성 확인#
GET, PUT, DELETE는 같은 요청을 반복해도 서버의 최종 상태가 같아야 합니다. 결제나 작업 생성처럼 중복 실행이 위험한 POST에는 idempotency key를 고려합니다.
정리#
좋은 API는 URL, 상태 코드, 오류 모델에서 예측 가능성을 제공합니다.