[ HTTP API ]
[ 설명 ]
- 가장 중요한 것은
리소스 식별
- 리소스와 행위는 구분되어야 한다
(최근스펙에는 Resource
라는 이름이 Representation
으로 바뀜)
- HTTP method
- 기본
- GET
- POST
- PUT : 리소스를 대체, 해당 리소스가 없으면 생성
- PATCH : 리소스 부분 변경
- DELETE
- 추가
- HEAD : GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
- OPTIONS : 대상 리소스에 대한 통신 가능 옵션을 설명 (CORS의
preflight request
)
- CONNECT
- TRACE
[ GET ]
- 리소스 조회
- 데이터는 url에 query param으로 전달
- 메시지 바디를 사용해서 데이터를 전달할 수 있지만,
지원하지 않는 서버도 있어서 권장되지 않음
[ POST ]
- 메시지 바디를 통해 서버로 요청 데이터 전달
- POST를 생성의 용도로만 사용한다고 알고 있는 것은 잘못된 것
- 주사용
1) 새 리소스 생성(등록)
2) 요청 데이터 처리
: 단순 데이터 생성, 변경을 넘어 프로스세를 처리해야 하는 경우 사용
3) 다른 메서드로 처리하기 애매한 경우
: JSON 데이터를 넘겨야 하는데 GET 메서드로 처리하기 애매한 경우
- 컨트롤 URI
- GET, POST 만으로 행위를 나타내기는 한계가 있음
- 그래서 동사로 된 리소스 경로를 사용해서 나타내기도 한다
- ex)
/orders/{orderId}/start-delivery
- 조회는 GET을 사용하는 것이 유리
- 캐시 등을 서버와 정해놓고 적용하는 경우가 많기 때문
[ PUT ]
- 리소스를 대체
- 있으면 대체
- 없으면 생성
- 즉, 덮어버린다고 이해하면 편함
- POST와 차이
- 클라이언트가 리소스 위치를 알고 uri에 지정
- ex)
/members/100
-> 100번째 멤버를 대체하거나 생성한다는 의미
[ PATCH ]
- 리소스를 부분적으로 변경할 때 사용
- 가끔 PATCH를 지원하지 않는 경우도 있을 때에는 POST를 권장
[ HTTP API 설계 예시 ]
- 데이터를 등록하는 방법
- POST 기반의 신규자원 등록 -> 대부분 사용
- PUT 기반의 신규자원 등록
- 데이터 등록
- POST
- 클라이언트는 등록될 리소스의 URI를 모른다
- 서버가 새로운 리소스의 URI를 생성
- ex) 유저 관리 서비스
[POST] /members
- 컬렉션(Collection)
- 서버가 관리하는 리소스 디렉토리
- 서버가 리소스의 URI를 생성하고 관리
- PUT
- 클라이언트가 등록될 리소스의 URI를 알고있어야 한다
- 클라이언트가 새로운 리소스의 URI를 지정
- ex) 파일 관리 서비스
[PUT] /files/{filename}
- 스토어(Store)
- 클라이언트가 관리하는 리소스 저장소
- 클라이언트가 리소스의 URI를 알고 관리
- HTTP Method로 URI 설계가 해결하기 애매한 경우
컨트롤 URI
로 해결
참고하면 좋은 URI 설계 개념
- 문서 (
document
)
- 컬렉션 (
collection
)
- 스토어 (
store
)
- 컨트롤러 (
controller
) / 컨트롤 URI