[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 메서드의 속성

출처: https://ko.wikipedia.org/wiki/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 메서드의 활용에 대한 내용을 정리해보겠습니다. 감사합니다.