API URI 설계 방법과 HTTP 메서드 정리

Genie·2021년 11월 21일

API URI 설계에서 가장 중요한 것은
리소스를 식별하는 것
HTTP 메서드와 특징, 이를 기반으로 한 API 설계 예시를 알아보자.
결론 : URI 설계 시, 리소스 만으로 최대한 설계해보고, 안되면 컨트롤 URI 를 사용해서 해결해보자.

리소스와 행위를 분리하자.

URI 는 리소스만 식별 한다.
리소스와 해당 리소스를 대상으로 하는 행위를 분리해야 한다.
- 예시
  - 리소스 : 회원
  - 행위 : 조회, 등록, 삭제, 변경
행위 구분 방법 : HTTP 메서드

행위(메서드)

GET: 리소스 조회
POST: 요청 데이터 처리, 주로 등록에 사용
PUT: 리소스를 대체, 해당 리소스가 없으면 생성
PATCH: 리소스 부분 변경
DELETE: 리소스 삭제

기타 메서드

HEAD: GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환
OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
CONNECT: 대상 자원으로 식별되는 서버에 대한 터널을 설정
TRACE: 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행

HEAD 는 본 적이 있었는데, OPTIONS , CONNECT , TRACE 는 거의 본적이 없었다.

GET Method

리소스 조회 시 사용
서버에는 query 를 통해서 전달
body 에 데이터를 넣을 수 있으나, 권장하지 않음

POST Method

대상 리소스가 리소스의 고유한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청한다.
메세지 BODY 를 통해 서버로 요청 데이터 전달
서버는 요청 데이터를 처리
- 단순히 데이터를 생성하거나 변경하는 것 외에 프로세스를 처리해야 하는 경우에도 사용됨.
- 프로세스의 상태가 변경되는 경우 (단순한 값 변경이 아님)
  - POST 결과로 새로운 리소스가 생성되지 않을 수 있음
  - 프로세스를 나타낼 때, 컨트롤 URI 를 활용하기도 한다. 이 경우에는 리소스만으로는 표현을 못할 수 있기 때문에 컨트롤 URI 로 표현된다.
신규 리소스 등록, 프로세스 처리 등에 이용된다.
어떠한 리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야 함 -> 정해진 것이 없음
다른 메서드로 처리하기 애매한 경우에도 사용함.

PUT Method

PATCH 와는 다르다. 리소스를 대체한다는 것

리소스를 대체
• 리소스가 있으면 대체
• 리소스가 없으면 생성
• 쉽게 이야기해서 덮어버림
클라이언트가 리소스를 식별
• 클라이언트가 리소스 위치를 알고 URI 지정
• POST와 차이점

PATCH Method

리소스 부분 변경 시 사용
PATCH 지원이 안되면 POST 써도 됨.

DELETE Method

리소스 제거 시 사용

HTTP 메서드의 속성

안전(safety) , 멱등(idempotent) , 캐시 가능(cacheable)

안전

호출해도 리소스를 변경하지 않는다.
계속 호출해서 장애가 발생하는 경우는 고려하지 않는다.

멱등 (idempotent)

f(f(x)) = f(x)
한 번 호출하든 100번 호출하든 결과가 같다.
GET , PUT , DELETE 는 멱등하다.
POST : 두 번 호출하면 같은 결제(또는 요청)가 중복해서 발생이 가능하다.
활용 예시(자동 복구 메커니즘)
- 서버가 timeout 으로 정상 응답을 못줄 때, 클라이언트가 같은 요청을 다시 해도 되는지에 대한 판단 근거에 활용이 된다.
외부 요인으로 중간에 리소스가 변경되는 건 멱등에 고려하지 않는다.

캐시가능 (Cacheable)

응답 결과 리소스를 캐시해도 사용해도 되는가?
가능한 메서드 : GET , HEAD , POST , PATCH
실제로는 GET , HEAD 정도 캐시를 사용한다.
- GET 은 URL 로 key 를 잡으면 되니까 간단함.
- POST , PATCH 는 body 까지도 key 로 고려해야 하는데, 구현하기 쉽지 않다.

클라이언트에서 서버로 데이터 전송 방식

쿼리 파라미터를 통한 데이터 전송

GET , 주로 정렬 필터에 사용이 된다.

메세지 바디를 통한 데이터 전송

POST, PUT, PATCH
회원가입, 상품 주문, 리소스 등록/변경

클라이언트에서 서버로 데이터를 전송하는 4가지 상황

1. 정적 데이터 조회

이미지, 정적 텍스트 문서 조회
리소스 경로만으로 가능
조회 니까 GET 사용

2. 동적 데이터 조회

쿼리 파라미터를 사용하여 동적 데이터를 조회한다.
검색, 게시판 목록, 정렬 필터, 정렬 조건 등에서 사용된다.
조회 니까 GET 사용

3. HTML FORM 데이터 전송

GET 이랑 POST 만 지원한다.
HTML Form submit시 POST 전송
이 상황에서는 웹 브라우저가 HTTP 메세지를 자동으로 생성해준다.
Content-type default 는 x-www-form-urlencoded
- 쿼리 파라미터 처럼 key,value 형태로 만들어서 body 에 만들어준다.
- 전송 데이터를 url encoding 처리해준다.
FORM 데이터 전송은 GET 메서드도 지원하지만, 사용하지 말자.
파일도 전송하고 싶다면 ?
- form 태그 안에 속성값에 enctype="multipart/form-data" 라고 추가를 해주면 됨.
  - 여러 컨텐트 타입을 같이 보낼 수 있다.

4. HTTP API 데이터 전송

서버 to 서버
• 백엔드 시스템 통신
앱 클라이언트
• 아이폰, 안드로이드
웹 클라이언트
• HTML에서 Form 전송 대신 자바 스크립트를 통한 통신에 사용(AJAX)
• 예) React, VueJs 같은 웹 클라이언트와 API 통신
POST, PUT, PATCH: 메시지 바디를 통해 데이터 전송
GET: 조회, 쿼리 파라미터로 데이터 전달
Content-Type: application/json을 주로 사용 (사실상 표준)
• TEXT, XML, JSON 등등

API 설계 예시

1. POST 기반 등록 예시

• 회원 목록 /members -> GET
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET ( 객체 인스턴스 하나를 다루는 경우를 문서 라고 한다.)
• 회원 수정 /members/{id} -> PATCH, PUT, POST
• 회원 삭제 /members/{id} -> DELETE

특징

클라이언트는 등록될 리소스의 URI를 모른다.
• 회원 등록 /members -> POST
• POST /members
서버가 새로 등록된 리소스 URI를 생성해준다.
• HTTP/1.1 201 Created
Location: /members/100
컬렉션(Collection)
• 서버가 관리하는 리소스 디렉토리
• 서버가 리소스의 URI를 생성하고 관리
• 여기서 컬렉션은 /members

2. PUT 기반 등록 예시

딱 ! 파일 등록이라고 생각하면 된다.

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET ( 객체인스턴스 또는 파일 하나를 다루는 경우를 문서 라고 한다.)
• 파일 등록 /files/{filename} -> PUT
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST

특징

클라이언트가 리소스 URI를 알고 있어야 한다.
• 파일 등록 /files/{filename} -> PUT
• PUT /files/star.jpg
클라이언트가 직접 리소스의 URI를 지정한다.
스토어(Store)
• 클라이언트가 관리하는 리소스 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• 여기서 스토어는 /files

3. HTML FORM 사용(순수한 HTML ,FORM)

• 회원 목록 /members -> GET
• 회원 등록 폼 /members/new -> GET ( 순수 HTML 페이지 )
• 회원 등록 /members/new, /members -> POST(순수 HTML 페이지에서 저장하기 버튼 클릭 시 요청하는 uri)
• 회원 조회 /members/{id} -> GET
• 회원 수정 폼 /members/{id}/edit -> GET ( 순수 HTML 페이지 )
• 회원 수정 /members/{id}/edit, /members/{id} -> POST (순수 HTML 페이지에서 저장하기 버튼 클릭 시 요청하는 uri)
• 회원 삭제 /members/{id}/delete(컨트롤 URI) -> POST

• 회원 등록 폼 /members/new -> GET
• 회원 등록 /members/new, /members -> POST
URL 은 웬만하면 통일해서 사용하자
POST 가 실패해서, get /members/new url 을 통해 폼으로 다시 돌아가야 할 경우, redirection 이 일어나면서 폼이 초기화 될 수도 있음.

HTML FORM은 GET, POST만 지원
- 다른 메서드를 사용하기 위해 AJAX 같은 기술을 사용해서 해결
컨트롤 URI
• 문서 , 컬렉션, 스토어로 해결하기 어려운 추가 프로세스를 실행한다.
문서, 컬렉션, 스토어가 뭔지 헷갈린다면 다시 스크롤을 올려 찾아보자.
• GET, POST만 지원하므로 제약이 있음
• 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
• POST의 /new, /edit, /delete가 컨트롤 URI
• HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)

Genie

차근차근

이전 포스트

HTTP 기본

다음 포스트