* API URI 설계
- URI 계층 구조를 활용하여 리소스 식별을 하는 것이 중요하다
ex) 회원 등록, 회원 수정, 회원 조회 등에서 resource는 회원이다.
--> 회원 resource를 URI에 mapping해야한다.
- URI는 resource만 식별함
- 리소스(명사)와 행위(동사)를 분리해야함
Method
* GET : resource 조회
- 데이터는 query(parameter, String)를 통해서 전달
- message body 사용해서 데이터 전달 가능. but 지원하는 곳이 잘 없어서 권장하지 않음
* POST : 요청 데이터 처리.
- message body 통해서 서버로 요청 데이터를 전달함
--> 서버는 요청 데이터 처리 (데이터 처리하는 모든 기능 수행)
- 주로 전달된 데이터는 신규 resource 등록, process 처리에 사용함
- 요청 데이터 처리 : 대상 resource가 고유의 한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청
ㄴ HTML 양식에 입력된 필드와 같은 데이터 블록 --> 데이터 처리 프로세스에 제공
ex) HTML FORM에 입력한 정보로 회원가입, 주문 등 사용됨
ㄴ 게시판, 뉴스 그룹, 메일링 리스트, 블로그, 유사한 기사 그룹에 message 게시
ex) 게시판 글쓰기, 댓글 달기
ㄴ 서버가 식별하지 않은 새 resource 생성
ex) 신규 주문 생성
ㄴ 기존 resource에 데이터 추가
ex) 문서 끝에 내용 추가
--> resource URI에 POST 요청 시 요청 데이터를 resource별로 어떻게 처리해야할지 정해야함 (정해진 것이 없음)
- 요청 데이터 처리할 때, 단순히 데이터 생성하거나 변경하는 것을 넘어 프로세스를 처리해야하는 경우
ㄴ POST 결과로 새로운 resource가 생성되지 않을 수 있음 (ex : 주문 -> 결제 완료 -> 배달 시작 -> 배달 완료)
--> 기본적으로는 resource로 최대한 URI를 설계하고, 어쩔 수 없는 경우에는 Control URI로 설계해야 한다.
- 다른 method로 처리하기 애매한 경우
- JSON으로 조회 데이터를 넘길 때 GET method를 사용하기 어려운 경우(애매한 경우) --> POST 사용
*** 조회하는 경우만 GET을 사용하고, 나머지의 경우에는 POST를 사용하면 된다.
* PUT : resource 대체 (덮어쓰기). 해당 resource 없는 경우엔 생성
- Client가 resource를 리소스 위츠를 알고 URI를 지정한다. 즉, resource를 식별함 (POST와의 차이점)
- 주의 : 기존에 있는 resource에 맞지 않게 전송하는 경우 --> resource 자체를 덮어쓰기 때문 (기존 정보 삭제됨)
* PATCH : resource 부분 변경 (이름 변경, 특정 필드 변경 등)
- PUT과 달리, 기존 resource를 덮어쓰지 않고, 부분 resource만 변경함
- HTTP에서 PATCH 자체를 받아들이지 못하는 경우 --> POST 사용하면 해결됨
* DELETE : resource 삭제
* 기타
- HEAD : GET과 동일하지만 message부분 제외하고 상태 줄과 header만 변환
- OPTIONS : 대상 resource에 대한 통신 가능 옵션(메서드)을 설명해줌 (주로 CORS에서 사용됨)
- CONNECT : 대상 resource로 식별되는 서버에 대한 터널 설정
- TRACE : 대상 resource에 대한 경로 따라 message loofback test 수행
Method 속성
* 안전 : Safe methods
- method를 호출했을 때 서버 상태(데이터)를 변경하지 않는 성질
- 그러나 단순히 조회만 하기 때문에, 여러 번 호출해도 서버 데이터는 그대로 유지됨
--> 로그가 쌓여 장애가 생겨도, 해당 resource만 고려함
* 멱등 : Idempotent Methods
- 호출을 반복해도 결과는 동일하는 성질
- 자동 복구 매커니즘을 사용하여, 서버가 TIMEOUT 등으로 정상 응답을 주지 못했을 경우
--> Client가 같은 요청을 해도 되는지 판단 근거를 마련함
- 그러나 재요청 중 외부 요인에 의해 중간에 resource가 변경되는 것까지 고려하지 않음
- GET, PUT, DELETE는 몇 번을 반복해도 결과가 동일
- POST는 요청으로 결제가 반복해서 일어나면 안되는 것처럼, 새로운 resource가 생기거나 중복처리 될 수 있음에 주의해야 함
* 캐시 가능 : Cacheable Methods
- 응답 결과 resource를 저장해서 다시 사용할 수 있는가에 대한 것
- web browser처럼 서버로부터 받은 응답을 저장한 뒤, 다음 요청 때 서버에 가지 않고 꺼내 써도 되는지를 의미
- GET, HEAD, POST, PATCH 캐시 사용이 가능하지만, 실제로는 GET, HEAD까지만 캐시로 사용한다
- POST, PATCH는 본문 내용까지 캐시 키로 고려해야하기 때문에 구현이 어려움
Client --> Server 데이터 전송
* 전송 방법
1. Query Parameter를 통한 데이터 전송
- GET을 사용
ex) 정렬 필터(검색어)
2. Message Body를 통한 데이터 전송
- POST, PUT, PATCH를 사용
ex) 회원 가입, 상품 주문, 리소스 등록, 리소스 변경 등
* 상황
1. 정적 데이터 조회
- GET으로 조회
- 일반적으로 query parameter 없이 resource 경로로 단순하게 조회 가능
ex) 이미지, 정적 텍스트 조회
2. 동적 데이터 조회
- GET으로 조회하며, query parameter 사용하여 데이터 전달
- 조회 조건을 줄여주는 필터, 조회 결과를 정렬하는 정렬 조건에 주로 사용함
ex) 검색, 게시판 목록에서의 정렬 필터 및 검색어
3. HTML Form을 통한 데이터 전송
- POST로 전송과 저장
ex) 회원 가입, 상품 주문, 데이터 변경
- 주의 : GET으로도 전송과 저장이 가능하지만, GET은 조회로만 사용해야함. 리소스 변경이 발생하는 곳에서 사용하면 안됨
- Content-Tyep : application/x-www-form-urlencoded 사용
ㄴ form 내용을 message body 통해서 전송. (key=value, query parameter 형식)
ㄴ 전송 데이터를 url encoding 처리
ex) abc김 -> abc%EA%B9%80 (utf-8 인코딩)
- Content-Type : multipart/form-data
ㄴ 파일 업로드 같은 binary data 전송 시 사용
ㄴ 다른 종류의 여러 파일과 폼 내용을 같이 전송 가능
- GET, POST만 지원함 (GET은 되도록 사용 x)
4. HTTP API를 통한 데이터 전송
- 서버 - 서버 : 백엔드 시스템 통신
- App Client : 아이폰, 안드로이드
- Web Client : HTML에서 Form 전송 대신 AJAX와 같은 자바 스크립트 통한 통신에 사용
ex) React, VueJs
- POST, PUT, PATCH : message body를 통한 데이터 전송
- GET : 조회, query parameter로 데이터 전달
- Content-Type : application/json을 표준으로 주로 사용함
ex) TEXT, XML, JSON 등
*** HTTP API 설계 예시
* HTTP API - Collection
- Client는 데이터를 보낼 때 어디에 저장될지 모르는 상태이며, Server가 데이터 받고 내부적으로 ID를 생성하고 주소를 결정함
- Server가 관리하는 resource 저장소
- Server가 resource의 URI를 알고 관리
ex) /members/100 (collection : /members)
* HTTP API - Store
- Client가 저장될 위치를 이미 알고 요청을 보냄
- Client가 관리하는 resource 저장소
- Client가 resource의 URI를 알고 관리
ex) /files/ex.jpg (store : /files)
- HTTP API는 Collections을 주로 쓰며, PUT을 쓰는 경우는 파일 업로드 이외에 거의 없음
* HTML FORM 사용
- web browser의 순수 HTML FORM은 GET과 POST만 사용할 수 있는 제약적인 방식
- PUT, DELETE 등 사용하기 위해선 Control URI를 사용함
--> 사용하기 위해 method 대신 URI 경로에 동작을 포함시킴
ex) POST /members/100/edit or delete
ㄴ 명사 위주로 설계하는 것이 원칙이지만, FORM에서는 예외적으로 허용한다.
간단정리
* document
- 단일 개념 (파일, 객체 인스턴스, 데이터베이스 row)
ex) /members/100, /files/ex.jpg
* collection
- server가 관리하는 resource 저장소
- server가 resource의 URI 생성 및 관리
ex) /members
* store
- Client가 관리하는 resource 저장소
- Client가 resource의 URI를 미리 알고 관리
ex) /files
* controller, controller URi
- 문서, collection, store로 해결하기 어려운 추가 process 실행
- 동사를 직접 사용
ex) /members/{id}/delete
참고 사이트 : REST API Tutorial
'공부 > spring' 카테고리의 다른 글
| [HTTP] Header - 일반 (0) | 2026.04.30 |
|---|---|
| [HTTP] State Code (2) | 2026.04.29 |
| [HTTP] HTTP 특징 (0) | 2026.04.27 |
| [HTTP] Internet Network, URI (0) | 2026.04.27 |
| [Spring] Bean Scope (2) | 2026.04.25 |