[HTTP] HTTP 메서드 총정리: API 설계를 위한 필수 개념
본 게시물은 모든 개발자를 위한 HTTP 웹 기본 지식 강의를 보고 작성하였습니다.
HTTP API 만들기
API(Application Programming Interface)는 프로그램 간 데이터를 주고받기 위한 약속된 규칙입니다.
웹 API는 HTTP 기반으로 만들어지며, 클라이언트(예: 브라우저, 앱)와 서버가 JSON 데이터를 주고받으며 통신합니다.
좋은 API URI 설계를 위해 예시를 들어보겠습니다.
<요구사항> 회원 정보 관리 API 만들기
- 회원 목록 조회
- 회원 조회
- 회원 등록
- 회원 수정
- 회원 삭제
URI를 아래와 같이 뜻 그대로 만들어봤습니다.
- 회원 목록 조회 /read-member-list
- 회원 조회 /read-member-by-id
- 회원 등록 /create-member
- 회원 수정 /update-member
- 회원 삭제 /delete-member
꽤나 그럴듯 하게 보이는데 과연 이게 좋은 URI 설계일까요?
-> 결론적으론 아닙니다.
URI를 설계할 때 가장 중요한 것은 "리소스" 입니다.
회원을 등록하고 수정하고 조회하는건 리소스가 아닙니다.
예) 미네랄을 캐라 -> 미네랄이 리소스!
즉, 회원이라는 개념 자체가 리소스 입니다.
따라서 리소스를 식별할 때는 등록, 수정, 조회 등의 행위는 모두 배제하고, "회원"이라는 리소스만 식별하면 됩니다.
이 회원 리소스를 URI에 매핑하는 것입니다.
- 회원 목록 조회 /members
- 회원 조회 /members/{id}
- 회원 등록 /members/{id}
- 회원 수정 /members/{id}
- 회원 삭제 /members/{id}
위와 같이 리소스를 식별하고, URI 계층 구조를 활용하여 URI를 설계했습니다.
하지만, 조회 등록 수정 삭제 <행위>를 구분할 수 없다는 문제점이 보입니다.
URI는 리소스만 식별하며,
리소스와 해당 리소스를 대상으로 하는 행위를 분리해야 합니다.
- 리소스: 회원
- 행위: 조회, 등록, 변경, 삭제
그렇다면, 위와 같은 문제점인 행위를 어떻게 구분할까요?
-> 여기서 HTTP 메서드를 이용합니다.
HTTP 메서드 종류
HTTP 메서드는 클라이언트가 서버에게 어떤 행동을 원하는지를 나타내는 명령어입니다.
즉, "서버야! 나 이거 할게~" 라고 알려주는 방식이에요.
주요 메서드의 종류는 아래와 같습니다.
- GET: 리소스 조회
- POST: 요청 데이터 처리, 주로 등록에 사용
- PUT: 리소스를 대체, 해당 리소스가 없으면 생성
- PATCH: 리소스 부분 변경
- DELETE: 리소스 삭제
1. GET - 리소스 조회
서버에 전달하고 싶은 데이터는 query(쿼리 파라미터, 쿼리 스트링)를 통해 전달
| 클라이언트가 서버에 members의 100번 데이터를 요청 | 서버는 members의 100번 데이터를 조회하고 JSON 응답을 생성 | 서버에서 응답 메시지를 만들어서 클라이언트한테 전달 |
| GET /members/100 HTTP/1.1 Host: localhost:8080 |
{ "username": "young", "age": 20 } |
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 34 { "username": "young", "age": 20 } |
2. POST - 리소스 등록
메시지 바디를 통해 서버로 요청 데이터 전달, 서버는 요청 데이터를 처리
| 클라이언트가 메시지 바디로 요청 데이터 전달 | 서버는 데이터를 받아 신규 리소스 식별자를 생성 /members -> /members/100 |
서버에서 새로 생성된 URI를 포함하여 응답 메시지를 만들고 클라이언트한테 전달 |
| POST /members HTTP/1.1 Content-Type: application/json { "username": "young", "age": 20 } |
{ "username": "young", "age": 20 } |
HTTP/1.1 201 Created Content-Type: application/json Content-Length: 34 Location: /members/100 { "username": "young", "age": 20 } |
POST는 요청 데이터를 어떻게 처리할까요? 이는 정해진 것이 없습니다.
리소스 URI에 POST 요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야 합니다.
POST는 여러가지 쓰임새가 있는데,
1. 새 리소스 생성(등록)
: 서버가 아직 식별하지 않은 새 리소스 생성할 때 사용합니다.
2. 요청 데이터 처리
: 단순히 데이터를 생성하거나, 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우에 사용합니다.
예) 주문에서 결제 완료 -> 배달 시작 -> 배달 완료 처럼 단순히 값 변경을 넘어 프로세스의 상태가 변경되는 경우에도 POST를 사용합니다. 그리고, POST의 결과로 새로운 리소스가 생성되지 않을 수도 있습니다.
3. 다른 메서드로 처리하기 애매한 경우
: 예시로, JSON으로 조회 데이터를 넘겨야 하는데, GET 메서드를 사용하기 어려운 경우에도 POST가 사용됩니다.
정리하자면, 조회 데이터는 GET을 쓰고, 그 외에 데이터가 변경되거나, 프로세스가 진행되거나, 어쩔 수 없는 경우에는 POST를 선택하면 됩니다!
3. PUT - 리소스 완전히 대체
PUT은 리소스가 있으면 대체하고, 리소스가 없으면 새로 생성합니다. 쉽게 얘기해서 덮어버린단 의미입니다.
클라이언트가 리소스 위치를 알고 URI를 지정하는 것이 POST와의 차이점입니다.
- POST: /members
- PUT: /members/100
<리소스가 있는 경우>
/members/100에 해당하는 리소스가 있으므로, 클라이언트가 보낸 데이터를 전체 덮어쓰기 합니다.
<리소스가 없는 경우>
/members/100에 해당하는 리소스가 없으므로, 서버는 신규 리소스를 생성하여 저장합니다.
<리소스 완전 대체 주의!>
/members/100에 해당하는 데이터의 형태가 달라도, 기존 데이터는 무시하고 클라이언트가 보내는 데이터로 완전히 덮어쓰기 당합니다.
4. PATCH - 리소스 부분 변경
데이터를 일부만 변경하고 싶다면, PUT을 쓰긴 굉장히 위험합니다. 이럴때 PATCH를 쓸 수 있습니다.
/members/100에 해당하는 리소스에서 age: 50만 보내도, 부분적으로 age만 데이터가 변경됩니다.
5. DELETE - 리소스 제거
/members/100에 해당하는 리소스를 제거합니다.
HTTP 메서드의 속성
1. 안전 (Safe Methods)
호출해도 리소스를 변경하지 않습니다.
GET - 수백번 호출해도 단순 조회기 때문에 리소스의 변경이 없어서 안전합니다.
POST, PUT, PATCH, DELETE - 한 번만 호출해도 리소스의 변경이 일어납니다.
2. 멱등 (Idempotent Methods)
한 번 호출하든 100번 호출하든 호출된 결과가 똑같습니다.
GET, PUT, DELETE - 특정 리소스 조회, 대체, 삭제기 때문에 결과가 항상 똑같기 때문에 멱등합니다.
POST - 여러번 호출하면 같은 행위가 중복 발생하여(ex. 결제) 결과가 달라집니다. 멱등이 아닙니다.
참고로 멱등은 외부 요인으로 중간에 리소스가 변경되는 것 까지는 고려하지 않습니다.
3. 캐시가능 (Cacheable Methods)
응답(Response)을 저장했다가 재사용할 수 있는지 여부를 나타냅니다.
즉, 클라이언트가 동일한 요청을 보낼 때, 서버에 다시 요청하지 않고 이전 응답을 그대로 사용할 수 있는가?를 판단하는 기준입니다.
GET, HEAD, POST - 캐시 가능
PUT, DELETE, PATCH - 캐시 불가능
HTTP 메서드 총 정리
| 메서드 | 설명 | 특징 | 예시 |
| GET | 리소스 조회 | 읽기 전용 | "나 이 책 좀 보여줘!" → 서버가 책 내용을 보여줌 |
| POST | 리소스 생성 | 서버에 새 데이터 생성 | "이 책 새로 추가해줘!" → 서버에 새 책이 추가됨 |
| PUT | 리소스 전체 수정 | 전체 데이터 덮어쓰기 | "이 책 내용을 전부 이걸로 바꿔줘!" → 전체 내용 교체됨 |
| PATCH | 리소스 부분 수정 | 일부분만 수정 | "책 제목만 고쳐줘!" → 일부만 바뀜 |
| DELETE | 리소스 삭제 | 데이터 삭제 요청 | "이 책 삭제해줘!" → 해당 책이 사라짐 |
end
이번 글에서는 HTTP 메서드의 개념과 특징을 정리해 보았습니다.
HTTP 메서드는 우리가 API를 설계할 때 꼭 이해해야 하는 중요한 개념입니다. 예전에는 APi를 설계할 때 행위를 URI에 넣는 실수를 종종 했었는데, RESTful한 설계를 이해하면서 URI는 리소스를 표현하고, 행위는 HTTP 메서드로 구분해야 한다는 개념을 확실히 알게 되었습니다.
다음 글에서는 HTTP 메서드의 활용에 대한 내용을 정리해보겠습니다. 감사합니다.