🖊️ API URI 설계
리소스 식별 중점
✔️ 리소스의 의미
회원CRUD를 예로 들어보자
회원 등록, 수정, 조회 자체가 리소스는 아니다.
회원 이라는 개념 자체가 리소스가 된다.
✔️ 리소스 식별방법
회원의 CRUD(기능)를 모두 배제하고
회원이라는 리소스만 식별 -> 회원 리소스를 URI에 매핑
✔️ 계층 구조를 활용
회원 목록 조회 /members
회원 조회 /members/{memberId}
회원 등록 /members/{memberId}
...
계층 구조상 상위를 컬렉션으로 보고 복수단어 사용 권장
그렇다면 어떻게 구분할까?
리소스와 행위를 분리 하는 것이다.
📬 GET,POST
✔️ GET : 리소스 조회
- 리소스 조회
- 서버에 전달하고 싶은 데이터는 query를 통해서 전달
- 지원하지 않는 서버가 많아서 메시지 바디를 허용하지 않는 곳이 많음
✔️ POST : 요청 데이터 처리, 주로 등록에 사용
-
새 리소스 생성 (등록)
- 서버가 식별하지 않은 새 리소스 생성
-
요청 데이터 처리
-
단순히 데이터 생성, 변경을 넘어서 프로세스를 처리해야 하는 경우
-
리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야 함 -> 정해진 것이 없음
-
-
메시지 바디를 통해 서버로 요청 데이터 전달
-
서버는 요청 데이터를 처리
- 메시지 바디를 통해 들어온 데이터를 처리하는
모든 기능을 수행
- 메시지 바디를 통해 들어온 데이터를 처리하는
-
신규 리소스 식별자를 생성 하고 응답 데이터에 Location을 넣어 식별자를 보냄
-
조회는
GET이 유리하지만POST는 캐싱이 어려움.
데이터 변경, 프로세스 변경, 어쩔수 없는 경우POST사용
✔️ PUT : 리소스를 대체, 해당 리소스가 없으면 생성
- 클라이언트가 리소스 위치를 알고 URI 지정
- 여기서 대체는
완전한 대체, 즉 덮어쓴다.
✔️ PATCH: 리소스 부분 변경
- 리소스 부분 변경
✔️ DELETE: 리소스 삭제
- 리소스 제거
✔️ 그외
-
HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
-
OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
-
CONNECT: 대상 리소스로 식별되는 서버에 대한 터널을 설정
-
TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행
🧫 메서드 속성
-
안전 (Safe Methods)
- 호출해도 리소스 변경 X
- 무한 호출로 로그 같은게 쌓여 장애가 발생해도 안전은 해당 리소스만 고려
-
멱등 (Idempotent Methods)
- 몇 번을 호출해도 결과가 같다.
- GET, PUT, DELETE
- 잘 모르겠다면 해당 메소드를 여러번 조회했을 때 결과를 생각해보자
- 활용
- 자동 복구 메커니즘
- 멱등은 외부 요인으로 중간에 리소스가 변경되는 것 까지는 고려 X
- 몇 번을 호출해도 결과가 같다.
-
캐시가능(Cacheable Methods)
-
GET,HEAD, POST, PATCH 캐시 가능
-
실제로는
GET,HEAD정도만 캐시로 사용 -
POST, PATCH는 본문 내용까지 캐시 키로 고려 -> 구현 어렵다.
-
📱 메서드 활용
✔️ 클라이언트에서 서버로 데이터 전송
데이터 전달 방식은 크게 2가지
✔️ 쿼리 파라미터를 통한 데이터 전송
- GET
- 정렬 필터(검색어)
✔️ 메시지 바디를 통한 데이터 전송
- POST,PUT,PATCH
- 회원가입, 상품 주문, 리소스 등록, 변경
✔️ 4가지 상황
-
정적 데이터 조회
-
이미지, 정적 텍스트 문서
-
조회는 GET 사용
-
정적 데이터는 일반적으로 쿼리 파라미터 없이 리소스 경로로 단순하게 조회 가능
-
-
동적 데이터 조회
-
검색, 게시판 목록에서 정렬 필터(검색어)
-
조회는 GET 사용
-
GET은 쿼리 파라미터 사용해서 데이터를 전달
-
-
HTML Form을 통한 데이터 전송
-
submit시 POST 전송 (회원가입, 상품 주문 , 데이터 변경)
-
Content-Type: application/x-www-form-urlencoded 사용
- form의 내용을 메시지 바디를 통해서 전송 (쿼리 파라미터 형식)
- 전송 데이터를 URL encoding 처리
-
HTML Form은 get 전송도 가능
-
-
Content-Type: multipart/form-data
- 파일 업로드 같은 바이너리 데이터 전송시 사용
- 다른 종류의 여러 파일과 폼의 내용 함께 전송 가능
HTML Form 전송은 GET, POST만 지원
-
HTTP API를 통한 데이터 전송
-
회원 가입, 상품 주문 데이터 변경
-
서버 to 서버, 앱 클라이언트, 웹 클라이언트 (Ajax)
-
POST, PUT, PATCH : 메시지 바디를 통해 데이터 전송
-
GET : 조회, 쿼리 파라미터로 데이터 전달
-
Content-Type: application/json 을 주로 사용 (사실상 표준)
- TEXT, XML, JSON 등
-
쿼리파라미터 : key=value
➰ 컬렉션과 스토어, HTML Form
✔️ 컬렉션
회원 등록 /members -> POST
-
POST 기반 등록
예) 회원 관리 API 제공 -
클라이언트는 등록될 리소스의 URI를 모름
-
서버가 리소스의 URI를 생성하고 관리
-
서버가 관리하는 리소스 디렉토리
-
여기서 컬렉션은
/members
✔️ 스토어
파일 조회 /files/{filename} -> GET
-
PUT 기반 등록
예) 정적 컨텐츠 관리, 원격 파일 관리 -
클라이언트가 리소스 URI를 알고 관리
-
클라이언트가 직접 리소스의 URI를 지정
-
클라이언트가 관리하는 리소스 저장소
-
여기서 스토어는
/files
✔️ HTML FORM 사용
회원 수정 /members/{id}/edit, /members/{id} -> POST
회원 삭제 /members/{id}/delete -> POST
- 웹페이지 회원 관리
- GETM POST만 지원 -> 제약이 있음 -> 컨트롤 URI
- AJAX 기술을 사용해서 해결 가능
- 여기서는 순수 HTML, HTML FORM 이야기
✔️ 컨트롤 URI
- POST의 /new, /edit, /delete가 컨트롤 URI
- HTTP 메서드로 해결하기 애매한 경우 사용 (HTTP API 포함)
리소스 개념을 가지고 uri를 설계 하고 안될 때 컨트롤 uri를 사용하자
❓HTTP API
- HTTP 프로토콜을 통해 데이터를 주고받는 인터페이스
- 설계 방식 중 하나로
HTML FORM,AJAX,JSON등을 통해 데이터를 전송
📖 출처 및 참고자료
