HTTP API 설계 방법과 HTTP 메서드와 특징

API URI 설계

 

• URI의 역할은 리소스를 식별하는 것이기 때문에 URI에 행동을 담아선 안 됩니다. 즉, 회원 조회에서 회원은 리소스이고 조회는 행동이기 때문에 URI에는 회원에 대한 리소스만을 표현해야하며 행위는 HTTP 메소드로 표현해야 합니다.

 

• 서비스가 커질 경우 URI를 리소스만을 가지고 표현이 불가능할 수도 있습니다. 이럴 경우 예외적으로 /orders/{orderId}/start-delivery와 같이 행위를 URI에 담는 경우도 있습니다. 이를 컨트롤 URI라고 부릅니다.

GET

 

• GET 메서드는 주로 리소스를 조회하기 위한 목적으로 사용됩니다.

 

• 서버에 전달하고 싶은 데이터는 query를 통해서 전달합니다.

 

• 메시지 바디를 사용해서 데이터를 전달할 수 있지만, 지원하지 않는 곳이 많아서 권장되지 않습니다.

POST

 

• 데이터 생성을 요청하거나 특정 프로세스를 요청하기 위한 목적으로 사용됩니다.

 

• 요청에 필요한 데이터는 주로 바디에 담아서 요청합니다.

 

• 다른 메서드로 처리하기 애매하거나 불가능할 때 주로 POST를 사용합니다.

PUT

 

• 리소스를 대체하거나 해당 리소스가 없으면 생성해야 할 때 사용합니다.

 

• 서버에 name, age 데이터가 있는 상태에서 name만을 PUT으로 요청하면 기존 서버에 있는 name과 age를 없애고 이번에 요청한 name으로 대체할 때 사용합니다.

PATCH

 

• 리소스를 부분 업데이트할 때 사용합니다.

DELETE

 

• 리소스를 삭제할 때 사용합니다.

 

• body는 사용할 수 없기 때문에 만약, 삭제 시 body가 필요하다면 주로 POST로 대체합니다.

기타 HTTP 메서드

 

HEAD

 

• GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환합니다. 주로 캐시된 데이터가 최신인지 여부를 확인할 때 사용하는 메서드입니다.

OPTIONS

 

• 대상 리소스에 대한 통신 가능 옵션을 확인할 때 사용합니다. 주로 CORS의 Preflight Request에서 본 요청이 가능한지 여부를 확인할 때 사용합니다.

HTTP 메서드의 속성

 

 

안전( Safe Method )

 

• 리소스를 변경하지 않는 메서드를 안전 메서드라고 합니다.

멱등성( Idempotent )

 

• 한 번 호출하든 여러 번 호출하던 결과는 똑같은 메서드를 멱등 메서드라고 합니다.

 

• GET, PUT, DELETE는 여러 번 호출해도 결과는 똑같기 때문에 멱등 메서드입니다.

 

• 예를들어서 POST로 결제를 요청할 경우 여러 번 호출할 수록 결제가 여러 번 되기 때문에 비멱등 메서드입니다.

 

• 멱등과 비멱등을 구별해야 하는 이유는 클라이언트가 메서드에 대한 응답을 제대로 못받았을 때 해당 요청을 다시 해도 되는가?를 판단할 때 사용합니다.

캐시 가능( Cacheable )

 

• HTTP 메서드에 따라서 응답 결과 리소스를 브라우저에 캐시하는 것을 의미합니다.

 

• GET, HEAD, POST, PATCH는 캐시가 가능한 메서드입니다. 하지만, POST와 PATCH는 본문 내용까지 캐시 키로 고려해야 하는데 구현이 쉽지 않기 때문에 주로 GET, HEAD만 캐시로 사용합니다.