Open vivienlacourba opened 9 years ago
Issue description updated as I actually forgot the version number, and also after some thought having hal
in the media type seemed like an overkill, it would have been either:
application/vnd.org.w3.api.v1.hal+json
application/vnd.org.w3.api.hal.v1+json
For future thoughts the JSON-LD media type is application/ld+json
.
Please do not create YAMT (Yet Another Media Type). Use application/ld+json
. Thanks.
:+1: to reuse an existing media type (application/hal+json
).
FWIW, my two API clients don't need this any more; cf https://github.com/w3c/w3c-api/issues/29#issuecomment-277301730.
Following discussions started with @tripu on issue #29 I went to the conclusion that it will make things easier if the W3C API had its own media type. That way we could clearly identify when link relations points to another W3C API resource (using the
type
property on link objects).@dontcallmedom also suggested we include the API version in the media type as done by GitHub.
FYI, several popular APIs are using their own media type:
application/vnd.com.sensiolabs.connect+xml
application/vnd.github.v3+json
Proposed W3C API media type:
application/vnd.org.w3.api.v1+json
Explanation:
vnd
indicates it is a vendor-specific MIME typeorg.w3.api
indicates it's the W3C APIv1
version1.x
of the API we would change the major version number only when we bring changes that break backward compatibilityhal
might be an overkill and would only be a human readable hint to indicates we follow HAL (the only official HAL media type beingapplication/hal+json
)+json
to says we follow the "application/json" sends back JSON objects (+json
)