REST API는 리소스의 표현을 주고받으며 클라이언트와 서버를 느슨하게 연결하는 인터페이스다. 웹에서는 URL로 리소스를 식별하고 HTTP 메서드와 상태 코드로 작업 의미를 표현하는 경우가 많다. JSON을 사용한다고 모든 인터페이스가 REST의 제약을 충족하는 것은 아니다. Microsoft의 REST 설계 안내
리소스와 표현
문서 서비스에서 리소스는 문서, 작성자, 발행 요청 등이 될 수 있다. 데이터베이스 테이블을 그대로 노출하기보다 사용자가 수행하는 작업과 공개할 정보를 중심으로 인터페이스를 정한다. 같은 문서도 목록에서는 제목만, 상세 화면에서는 본문까지 표현할 수 있다.
| 요청 예시 | 의미 |
|---|---|
| GET /articles/42 | 특정 문서의 표현 조회 |
| POST /articles | 새 문서 생성 요청 |
| PATCH /articles/42 | 문서 일부 변경 |
| DELETE /articles/42 | 문서 삭제 요청 |
이 경로는 설계 예시이며 실제 서비스에서 실행할 주소가 아니다. 메서드 의미와 멱등성은 HTTP Semantics 명세를 따른다.
요청마다 필요한 정보
상태 비저장 원칙은 서버에 데이터베이스를 두지 않는다는 뜻이 아니다. 각 요청을 이해하는 데 필요한 인증과 작업 맥락을 요청에 담아 특정 서버의 대화 상태에 의존하지 않도록 하는 것이다. 응답에는 결과뿐 아니라 다음 작업에 필요한 링크나 식별자를 제공할 수 있다. HTTP 캐시도 공개 범위와 최신성 조건에 맞춰 설계한다.
재시도와 오류
네트워크 오류 후 같은 생성 요청을 다시 보내면 중복이 생길 수 있다. API 계약에 멱등성 처리와 충돌 응답을 정의하고, 비동기 작업은 접수와 완료를 구분해야 한다. 인증 실패, 권한 부족, 입력 오류를 클라이언트가 판단할 수 있는 형태로 돌려준다.
OpenAPI 문서로 요청·응답 구조를 기술하면 도구 연동에 도움이 된다. 다만 문서가 있다는 이유로 실제 구현과 일치한다고 보장되지는 않으므로 계약 검사를 함께 유지한다.