RESTful API와 MediaTypes
Media-Types은 값을 Value 를 제공한다.
대부분의 HTTP API는 Media types를 올바르게 사용하는 것의 장점을 활용하지 못한다. 거의 application/json을 사용하고 호출하면 끝이다. 클라이언트는 어떻게 데이터를 읽어와야 할지 전혀 알지 못하게 되고, JSON 디코더를 사용하는 방법밖에 없게 된다. 이는 마치 html 파일을 ‘.txt’ 파일 확장자로 사용하는 것과 같다. 그 파일이 일반적인 text라는 관점에서는 맞지만, 그 파일을 읽어와 웹 페이지에 렌더링 해야된다는 정보를 전달하는데는 최악이다.
Media types 는 API가 클라이언트에게 어떻게 데이터를 payload 에서 읽어와야하는지 알려준다. 이건 API에 hypermedia를 더해주는 것보다 훨씬 어렵다. 올바른 media types는 payload의 구조를 강요?(enforce) 하고 payload 데이터가 무슨 뜻인지 알려준다.
이게 바로 대부분 API가 application/json을 사용하는 이유다. 만약 당신이 운이 좋다면, 데이터(위 문단에서 말하는 payload에 있는 데이터)를 설명해주는 문서가 있을 것이다. 우리는 클라이언트 개발자가 JSON을 읽고, 경험을 기반으로 해석하기를 기대하는 것 같다.
이 경우의 가장 좋은 예는 “text/html” Media type이다. 이 Media type의 payload가 주어지면 웹 브라우저는 자동으로 정보를 렌더링할 수 있다. 그 이유는 text/html payload 가 있는 문서를 보내는 모든 서버가 동일한 의미에 대해 동일한 태그를 보내기 때문이다. (html이라고 써있으면 html이란 뜻이다.)
API 세계도 마찬가지지만, 생각을 해야되고 더 어렵기 때문에 위처럼 활용하지 않는다.
media-types의 3가지 용도
- 일반 : application/json(or application/xml)
- 사용자 지정 : e.g. application/vnd.github.v3+json
- 표준: HAL, Collection+JSON or JSON-API, etc.
일반적인 media type을 사용하는 것과 사용자 지정 media type을 사용하는 것에 실무적인 차이가 있지는 않다. 클라이언트 개발자로서 API와 어떻게 소통해야 하는지 모르거나 그 payload와 어떻게 처리해야 할지 모르게 된다. 이 API를 사용하기 위해 구글링을 해야하거나 충분한 문서들을 찾아야 한다.
그러니까 media type 잘 설정해서 쓰자! (나머지 내용 생략 ㅎㅎ)
내가 궁금했던 데이터 타입
- JSON HAL (Hypertext Application Language): Json으로 하이퍼 링크를 표현하기 위한 규칙을 설정하는 표준이다.
2. HAL: 웹 API를 개발하고 일련의 링크로 노출 할 수있는 일반 미디어 유형이다.
3. HAL_JSON :Public constant media type for application/hal+json.
4. HAL_JSON_VALUE: A String equivalent of HAL_JSON
GET /orders/523 HTTP/1.1
Host: example.org
Accept: application/hal+json
HTTP/1.1 200 OK
Content-Type: application/hal+json
{
"_links": {
"self": { "href": "/orders/523" },
"warehouse": { "href": "/warehouse/56" },
"invoice": { "href": "/invoices/873" }
},
"currency": "USD",
"status": "shipped",
"total": 10.20
}URI 가 “/orders/523”인 주문 리소스를 나타내는 HAL 문서이다. “warehouse”, “invoice”링크가 있고, “currency”, “status”, “total” 프로퍼티들의 형태로 해당 링크만의 상태가 있다.
번역 출처
