REST는 「웹의 자원(resource)을 URL로 식별하고, HTTP 메서드로 행위를 표현」하는 API 설계 스타일입니다.
모든 회사가 엄격하게 따르진 않지만 사실상 표준 어휘입니다.
URL은 자원의 「명사」.
/users (목록), /users/123 (단건), /users/123/posts (123번 사용자의 글들).
동사는 안 씀(/getUsers, /createUser는 안티패턴).
HTTP 메서드로 행위 구분.
GET — 조회(부수효과 없음), POST — 생성, PUT — 전체 교체, PATCH — 부분 수정, DELETE — 삭제.
같은 URL이라도 메서드에 따라 다른 의미.
상태 코드를 의미 있게.
200 OK, 201 Created(생성됨), 204 No Content(빈 성공 응답), 400 Bad Request(요청 형식 오류), 401 Unauthorized(인증 필요), 403 Forbidden(권한 없음), 404 Not Found, 422 Unprocessable Entity(검증 실패), 500 Internal Server Error.
버전 관리.
URL 경로(/v1/users)나 헤더(Accept: application/vnd.api+json; version=1)로.
한 번 배포한 API는 호환성을 유지해야 클라이언트가 안 깨집니다 — 큰 변경은 v2로 분리.
한 줄 요약
REST는 URL은 명사·HTTP 메서드는 행위, 상태 코드는 의미 있게, 호환성은 버전으로 관리하는 설계 스타일입니다.
사실상 API 표준 어휘.
더 알아볼 것
- GraphQL과의 비교
- HATEOAS — 링크로 탐색
- API 디자인 가이드 — Google·Microsoft 문서
