[API] REST - 자기 서술적 메시지

자기 서술적 메시지 (self-descriptive messages)

 API 통신에서 요청과 응답은 모두 문자열을 형태로 전달됩니다. 때문에 API를 통해 사전에 약속된 내용이 아닌 정보는 상대가 해석하기 어려울 수 밖에 없습니다. 이 때문에 좀 더 다양한 종류의 정보를 보내기 위해서는 메시지 자신이 어떤 내용을 담고 있는지 스스로 설명할 수 있어야 합니다. 이를 자기 서술적 메시지라고 합니다.

 메세지가 자신을 설명할 수 있으려면 메세지의 구조, 의미 등을 해석할 수 있는 방법을 함께 전달해야 합니다.

이를 전달 할 수 있는 방법은 크게 두 가지가 있습니다.

1. Content Type: Media type

 Content Type 헤더는 해당 문서의 데이터가 어떤 종류(텍스트, 이미지, 프로그램 등)인지를 나타냅니다.

헤더의 값은 media type 값이 올 수 있는데, 이는 큰 범주의 main type과 세부 범주의 sub type으로 나뉩니다.

예를 들어 content type이 html 형식이면 헤더 값은 text/html이 되며,

json 형식이면 application/json이 됩니다.

// 클라이언트에서 서버에게 특정 기능을 수행합니다
fetch('/create-payment-intent', {
    method: "POST",
    // 요청과 함께 보내는 메세지가 json 타입임을 명시합니다.
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(this.sampleData),
}).then((res) => res.json())
  .then((res) => this.setClientSecret(res.clientSecret))

일반적으로 media type에 대한 정의는 IANA(Internet Assigned Numbers Authority)에서 관리합니다.

https://www.iana.org/

Internet Assigned Numbers Authority

현재 IANA에 등록된 타입들은 다음과 같습니다.

application	특정 애플리케이션을 통해 해석 또는 실행되는 데이터
/octet-stream, /pdf, /zip, /json, /x-www-form-urlencoded 등
audio	오디오 또는 음악데이터
/mpeg, /vorbis 등
font	글꼴
/woff, /ttf, /otf 등
image	비트맵 및 벡터 이미지 & 애니메이션
/jpeg, /png, /svg, /gif 등
mode	3D 모델링
/3mf, /vrml 등
video	영상
/mp4 등
text	읽을 수 있는 콘텐츠 또는 csv 형태의 데이터
/plain, /csv, /html, /css, /javascript 등

 IANA에 등록된 타입 말고도 multipart라는 타입도 존재합니다.

이는 파일을 업로드 하는 기능과 같이 텍스트(text/plain)나 이미지(image/png) 등

여러 종류의 데이터를 한 번에 보내야 하는 경우 사용됩니다.

대표적으로는 multipart/form-data가 있습니다.

 

2. link: Profile

 Link 헤더에 api에 대한 설명 문서를 가리키는 링크(profile)를 작성하여 메세지를 설명합니다.

 자기 서술적 메시지는 HTML 형식을 주고 받을 경우 지키기 쉽습니다. 문서 자체의 태그를 통해 각 요소들의 기능을 쉽게 추론할 수 있기 때문입니다. 하지만 API는 json 형식으로 요청과 응답을 주고받기 때문에, 이런 방식들로 추가적인 문서를 함께 보내야 합니다. 그래서 API 통신에서 자기 서술적 메시지의 조건을 지키기 어렵고, 실제로 잘 지켜지지 않기도 합니다.