[요약] REST API 디자인 규칙 - 04. 메타데이터 디자인

바디 정보

Content-Type

• 요청 또는 응답의 BODY 데이터 타입을 기술.

Content-Length

• 바디의 크기를 byte 단위로 기술한다.
• 드물게, utf-8 처리를 제대로 하지 않아 한글을 자소단위로 처리하여 Content-Length 를 잘못 구성하는 라이브러리도 존재 하므로 오류 발생시 이 부분도 고려.

Location

• 새로 생성한 리소스의 URI 를 나타낸다.
• Content-Location 과는 다르다!

조건부 요청

GET, POST, DELETE 는 리소스에 대한 변경을 수행하며, 서버는 조건부 수행을 지원해야 한다.

Last-Modified

리소스의 마지막 변경 시점을 나타낸다. Last-Modified 와 관련하여 아래의 조건식을 사용할 수 있다.

 If-Unmodified-Since

• 지정한 타임스탬프 이후로 수정한 내역이 없다면 이 요청을 처리한다.

If-Modified-Since

• GET, HEAD 에만 사용할 수 있다.
• 지정한 타임스탬프 이후로 수정한 내역이 있다면 이 요청을 처리한다.
• 주로 캐시 갱신에 사용한다.

ETag

Entity Tag. 리소스의 고윳값으로, ETag 값이 바뀌었다면 해당 리소스가 바뀌었다고 판단할 수 있다. ETag 와 관련하여 아래의 조건식을 사용할 수 있다.

If-Match

• 리소스가 주어진 ETag 목록 중 하나라도 일치하는 경우 이 요청을 처리한다.

If-None-Match

• 리소스가 주어진 ETag 목록 중 하나라도 일치하는 것이 없는 경우 이 요청을 처리한다.
• 주로 캐시 갱신, 덮어쓰기 방지를 위해 사용한다.

캐시

REST API 는 Cache 를 지원해야 하며, 동시에 Cache 를 사용하지 않도록 지정할 수도 있어야 한다.

Cache-Control, Expires, Date, Pragma

캐시를 사용하도록 지정

• 캐시를 사용함으로써 네트워크 부하를 줄일 수 있다.
• Cache-Control: max-age 를 이용하여 캐시의 갱신주기를 전달한다.
• HTTP 1.0 호환: Expires, Date 헤더를 추가하여 클라이언트가 캐시의 갱신 주기를 추정하도록 할 수 있다.

캐시를 사용하지 않도록 지정

• 캐시 사용이 불필요하거나, 사용해서는 안되는 경우 캐시를 사용하지 않도록 지정한다.
• Cache-Control: no-cache 또는 no-store 를 지정한다.
• HTTP 1.0 호환: Pragma: "No-cache / Expires: 0" 헤더 추가.

캐시 헤더 추가

• 캐시 헤더는 정말 캐시가 필요한 문서에만 추가한다.
• 200: GET 과 HEAD 요청은 캐싱에 적합하다.
• POST, UPDATE, DELETE: 리소스를 변경하는 행위의 응답은 캐시가 가능하지만, 캐싱에 적합한 대상은 아니다.
• 3xx, 4xx: 네거티브 캐싱. 오류로 인한 서버의 부하를 줄이기 위해 사용할 수 있다.

미디어타입

미디어 타입은 요청, 응답의 바디 데이터를 식별하기 위한 값으로 IANA 에서 관리한다. 누구나 제안을 할 수 가 있다. 구 MIME 을 지금은 미디어 타입이라 부른다.

기본 규칙

• Content-Type: {type}/{subtype}(; {parameter})
• 널리 쓰이는 타입들
  • text/plain
  • text/html
  • image/jpeg
  • application/xml
  • application/json
  • ...

벤더 고유 미디어 타입

벤더사의 고유 미디어 타입이 필요한 경우 벤더 접두사를 사용하여 신청 가능하다.

• Content-Type: {type}/vnd.{subtype}(; {parameter})
• 예시
  • application/vnd.ms-excel
  • application/vnd.lotus-notes
  • text/vnd.sun.j2me.app-descriptor

리소스 협상

• 클라이언트가 원하는 미디어 타입이 있는경우 이를 서버에 알릴 필요가 있다.
• 서버가 여러 미디어 타입으로 응답을 제공할 수 있고, 클라이언트가 요청한 미디 타입으로 응답이 가능하면 이를 받아들여 클라이언트가 원하는 미디어 타입의 응답을 제공할 수 도 있다.
• Accept: {type}/{subtype}