HTTP 메소드와 상태 코드는 API 설계의 기본 요소이며,
명확한 자원 표현과 구조적 응답은 효율적이고 안정적인 통신을 보장한다.

참고 | https://developer.mozilla.org/ko/docs/Web/HTTP/Methods

HTTP 메소드와 자원 조작

HTTP 메소드는 웹 자원을 관리하고 조작하기 위해 사용하는 행동 지침이다.
GET, POST, PUT, DELETE 등의 메소드는 자원과 상호작용하는 명확한 규칙을 제공한다.
이를 통해 클라이언트와 서버는 서로 일관되고 효율적으로 소통할 수 있다.

---

HTTP 메소드 기본 개념

HTTP 메소드의 주요 역할

HTTP 메소드	역할	특징
GET	자원을 읽어오는 요청	데이터 변경이 없는 안전한 요청이다. 자원 목록을 주로 가져오며, 응답 데이터는 JSON 등으로 제공된다.
POST	새로운 자원을 생성	데이터베이스에 새로운 항목을 추가한다. 요청 성공 시 새 자원의 JSON 표현을 응답으로 반환한다.
PUT	기존 자원의 전체를 수정	수정된 자원의 전체 데이터를 제공한다.
PATCH	기존 자원의 일부를 수정	자원의 일부만 수정할 때 사용한다.
DELETE	자원을 삭제	서버에서 특정 자원을 제거한다.

• HTTP 메소드 선택의 중요성
  • 각 메소드는 명확한 역할과 제약 조건을 가지고 있다.
  • 올바른 메소드를 사용하면 클라이언트와 서버 간의 의사소통이 더 효율적이고 안정적으로 이루어진다.

---

EX1) GET 요청 | 자원 조회

GET /members HTTP/1.1
Host: api.example.com

응답:

{
  "members": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

• 설명:
  • 클라이언트는 멤버 목록을 조회하기 위해 GET 요청을 보낸다.
  • 서버는 JSON 형식으로 응답하며, 이 데이터는 조회만 가능하고 변경되지 않는다.

---

POST PUT PATCH 기본 비교

메소드	주요 용도	특징
POST	자원 생성	새로운 자원 생성
PUT	자원 교체	전체 자원 교체 (미포함 필드는 null)
PATCH	부분 수정	전달된 필드만 수정 (나머지 유지)

핵심 차이점

구분	POST	PUT	PATCH
용도	생성	전체 교체	부분 수정
기존 필드 처리	-	삭제	유지
멱등성	X	O	X

cf. 멱등성이란?
멱등성이란 동일한 연산을 여러 번 수행해도 결과가 달라지지 않는 성질을 말한다.
네트워크 지연, 중복 요청 등의 문제를 해결하는 데 도움을 주기 때문에 중요함.

초기 데이터

{
    "username": "harry",
    "age": 30
}

PUT 요청 _ 전체 교체

PUT /members/1
Content-Type: application/json
{
    "username": "mike"
}

PUT 응답 _ 전체 교체

HTTP/1.1 200 OK
Content-Type: application/json
{
    "username": "mike",
    "age": null
}

PATCH 요청 _ 부분 수정

PATCH /members/1
Content-Type: application/json
{
    "username": "mike"
}

PATCH 응답 _ 부분 수정

HTTP/1.1 200 OK
Content-Type: application/json
{
    "username": "mike",
    "age": 30
}

메소드별 주요 특징 비교

구분	POST	PUT	PATCH
주요 용도	자원 생성	자원 교체	자원 부분 수정
기존 필드 처리	-	삭제 (null)	유지
멱등성	X	O	X
응답 코드	201 Created	200 OK	200 OK

💡 참고사항

• 기술적으로는 세 메소드 모두 생성/수정 가능
• REST 원칙상 용도에 맞는 사용 권장
• API 설계 시 상황에 따라 선택적 구현 가능

HTTP 상태 코드

HTTP 상태 코드는 요청의 성공 여부와 서버의 상태를 클라이언트에 전달하는 데 사용된다.

범위	설명	예시
1xx	정보 전달	100 Continue - 요청 진행 가능
2xx	성공	200 OK - 요청 성공
3xx	리다이렉션	301 Moved Permanently - 리소스 이동
4xx	클라이언트 오류	404 Not Found - 자원 없음
5xx	서버 오류	500 Internal Server Error - 서버 문제

• 상태 코드의 중요성
  • 상태 코드는 요청의 성공 여부를 명확히 전달하며,
    클라이언트는 이를 바탕으로 후속 작업을 결정한다.
  • 예를 들어:
    • 200 OK는 요청이 성공적으로 처리되었음을 의미한다.
    • 404 Not Found는 요청한 자원이 서버에 없음을 의미한다.

---

자원 표현과 통신

클라이언트와 서버는 HTTP 요청과 응답을 통해 자원을 주고받으며 통신한다.

1. URI를 통한 자원 식별

   • URI는 특정 자원을 명확히 가리켜야 한다.
   • 예:

     /api/v1/members/1

     • 위 URI는 1번 멤버라는 특정 자원을 의미한다.

2. JSON 기반의 응답 데이터

   • 자원의 상태와 정보를 직관적으로 나타낸다.
   • 예:

     {
       "id": 1,
       "name": "Alice"
     }

3. 상태 코드와 응답 데이터의 조화

   • HTTP 응답은 항상 상태 코드와 데이터를 함께 제공해야 한다.
   • 예:
     • 201 Created와 함께 새 자원의 URI 반환.
     • 204 No Content는 DELETE 요청 성공을 의미한다.

---

API 설계 시 고려 사항

1. 명확하고 간결한 URI

   • URI는 자원을 정확히 표현해야 한다.
   • 예: /members/1는 특정 멤버에 대한 정보를 나타낸다.

2. 일관된 JSON 응답 구조

   • 클라이언트는 항상 같은 형식의 데이터를 기대할 수 있어야 한다.
     • 예: 모든 API 응답은 { "status": "success", "data": ... } 형식을 따른다.

3. 적절한 상태 코드 사용

   • 성공, 실패, 리다이렉션 등을 정확히 전달한다.
   • 예:
     • PUT 요청 성공 시 200 OK.
     • 리소스가 존재하지 않을 경우 404 Not Found.

---