[REST 설계] 헤더 / 바디 디자인

HTTP 의 헤더를 통해 전달되는 여러 형태의 메타데이터 패턴

---

 

이전 글 : HTTP 메소드와 응답코드

2023.04.25 - [Engineering/SW Design] - [REST 설계] HTTP 메소드와 응답코드

[REST 설계] HTTP 메소드와 응답코드

 

 

 

HTTP 헤더

여러 형태의 메타데이터는 HTTP 요청 및 응답메시지에 포함된 헤더를 통해 전달된다.

HTTP는 표준 헤더 집합을 가지고 있으며, 헤더 집합 중 일부 영역은 요청된 리소스 관련 정보를 제공한다.

메시지에 전달되는 표현 관련 정보도 있으며 중간캐시를 조절하는 지시자 역할을 하기도 한다.

• Request header 의 예시
  

• Response header 의 예시
  

규칙1) Content-Type 을 사용 한다.

Content-Type 헤더는 요청/응답 메시지 바디에 있는 데이터 타입을 나타내며, 일반적으로 미디어 타입으로 알려진 특별하게 정의된 string 값이다.

클라이언트와 서버는 이 헤더 값을 참조하여 메시지 바디에 있는 컨텐츠를 해석한다.

• text/html, application/json 등의 형태를 가진다.

규칙2) Content-Length 를 사용 한다.

Content-Length 헤더는 바이트 단위로 바디의 크기를 나타낸다.

클라이언트는 응답메시지에 포함된 이 헤더 값을 보고 바이트의 크기를 올바로 읽었는지를 알 수 있고, HEAD 메서드 요청을 사용하여 메타데이터만 스캔 하는 것으로도 바디의 크기를 미리 알 수 있게 된다.

 

규칙3) Last-Modified 는 응답 메시지에서만 사용한다.

이 응답 헤더 값은 timestamp 를 의미 하며, 리소스의 상태 값이 바뀐 마지막 시간을 나타낸다.

클라이언트와 캐시 중간자는 이 헤더 값을 사용하여 클라이언트에 저장되어 있는 리소스를 갱신 할지 여부를 결정한다.

 

규칙4) ETag는 응답 메시지에서만 사용 한다.

이 응답 헤더 값은 응답 바디에 포함된 표현 상태의 특정 버전을 나타내는 string 값이다.

이 값은 리소스의 상태에 따라 바뀔 수 있으며 항상 GET 메서드 요청에 대한 응답으로 보내져야 한다.

클라이언트가 GET요청을 자주 하는 경우, 이 ETag 값을 별도로 저장해두고 나중에 요청할 GET 호출 여부를 판단하는 기준으로 사용 될 수 도 있다. 이러한 장치를 통해 호출에 드는 시간과 네트워크 대역폭을 절약 할 수 있다.

 

규칙5) Location 은 새로 생성된 리소스의 URI를 나타내는데 사용 해야 한다.

이 응답 헤더 값은 클라이언트의 관심 범위에 있는 리소스를 식별하는 URI다.

서버측에 성공적으로 리소스를 생성 했다는 응답이며, API는 헤더값의 location 속성에 새로 생성된 리소스의 URI를 명시 해서 리턴 해줘야 한다.

 

규칙6) Cache-Control, Expires, Date 응답 헤더는 캐시 사용을 권장 하는데 사용해야 한다.

캐싱은 클라이언트의 대기시간을 줄이고 API 부하를 감소시키는 장점이 있다.

리턴을 제공할때 Cache-Control 헤더 속성에 초단위의 max-age를 추가해주며, 이것이 의미 하는 바는 캐시의 갱신 주기 이다.

• ex) Cache-Control : max-age=60, must-revalidate

또한 응답의 시점을 나타내는 Date와 함께, 캐시의 만료일을 나타내는 Expires 헤더도 함께 제공한다.

Expires는 Date 에 갱신주기가 추가된 시점 정보로 이 차이로 갱신 주기를 역산 할 수 도 있다.

또한 no-cache 지시자는 캐시응답이 제공 되는 것을 막는데, 왠만하면 no-cache옵션은 쓰지 말고 값이 매우 작은 max-age를 주는 것으로 사용하는 것이 효과적이다.

 

규칙7) 커스텀 헤더는 HTTP 메서드의 행동자체를 바꾸는데 사용 하면 안된다.

커스텀 헤더는 정보전달이 목적일 때만 선택적으로 사용할 수 있으며, 커스텀 해더를 쓰더라도 클라이언트/서버 양쪽에서 문제 없도록 구현 되어야 한다.

만약 커스텀 HTTP헤더로 전송하련는 정보가 API 본연의 목적을 달성하기위해 중요한 정보라면, 그 정보는 request / response body 영역에 포함시키거나 URI에 포함시키는것이 맞는 패턴이다.

 

 

미디어 타입

request, response 의 body 안에 있는 데이터 형태를 식별하기 위해 넣는 Content-Type 헤더 속성을 미디어 타입이라고 하며 type “/” subtype 의 형식을 가진다.

type 값으로는 아래 값 들 중 하나가 될 수 있다.

• application, audio, image, message, model, multipart, text, video

subtype 다음에 key value 같은 형태로 파라미터를 붙여 쓸 수 있고 구분자를 ; 으로 한다.

다음은 주요 미디어 타입의 예시와 설명이다.

• text/plain
  • 특별한 콘텐츠 구조나 마크업이 없는 평문 포맷
• text/html
  • HTML 로 포맷 된 컨텐츠
• image/jpeg
  • JPEG에서 표준화한 이미지 압축 방법
• application/xml
  • XML로 구조화 된 콘텐츠
• application/javascript
  • js 로 작성 된 소스 코드
• application/json
  • 구조화 된 데이터를 교환하는 프로그램에서 주로 사용 되는 텍스트 기반의 JSON 포맷

 

HTTP 메시지 바디 포맷

REST API는 요청 메시지가 지정한 리소스의 상태를 응답 메시지의 바디를 이용해서 전달 하는데, 주로 텍스트 기반의 포맷을 이용하여 리소스 상태를 표현한다.

주로 XML, JSON 포맷으로 통용 되는데 과거 Soap 방식의 인터페이스가 성행할때 주로 사용되던 XML 보다는 Json 이 더 대중적으로 사용 되고 있다.

• HTTP 메시지 바디 xml 포맷 예시

• HTTP 메시지 바디 json 포맷 예시

 

 

---

REST API 의 request, response 에 들어가는 헤더 규칙에 대해 알아보았다.

미디어 타입 등 여러 클라이언트/서버의 상태를 알려주는 헤더 속성들을 통해 클라이언트와 서버는 각 역할과 책임의 범위 안에서 상대측의 정보를 얻을 수 있다.

API 헤더와 바디 속성들은 HTTP 표준 규약을 그대로 상속 받고 있으며, 이러한 패턴이 잘 지켜 질때 효과적인 인터페이스가 가능해진다.