Menu
I'm using Spring to create a RESTful service and I'm curious about the syntax for media-types.
From my understanding, the general media-type for HAL+JSON is application/hal+json. Also, from my understanding, a vendor-specific custom media-type that supports HAL+JSON would be something like application/vnd.api.entity.hal+json. However, I have also seen application/vnd.api.entity+hal+json. Which one is correct?
Also, what would the correct wild-card type be for HAL+JSON? Would it be application/*.hal+json or application/*+hal+json. Links to any pertinent RFC's would be appreciated. Thanks!
522
HAL) is an open specification that provides a structure to represent RESTful resources. It defines two hypermedia types to extend for XML and JSON. Initially proposed in 2011 by Mike Kelly, HAL is hardly a newcomer and has been used extensively in countless projects to organise and structure APIs.
Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures. With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia.
HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. The HAL format is strictly coupled to HATEOAS. The main target of HATEOAS is to decouple the API Consumer from the paths used in the API.
Hypermedia is an important aspect of REST. It lets you build services that decouple client and server to a large extent and let them evolve independently. The representations returned for REST resources contain not only data but also links to related resources.
application/vnd.api.entity+json
application/vnd.api.entity.hal+json would only make sense if you plan to provide your data also without support for HAL. The client has to know the structure of the content anyway and HAL is part of it.
application/vnd.api.entity+hal+json is just wrong. The standard states that only registered suffixes should be used. It also refers to them as "Structured Syntax Suffixes". So it's quite clear that it's about how to read data not about its meaning. Only one suffix is allowed and more wouldn't make sense.
Think about it as application/semantic+syntax, or application/what's in it + how to read it.
67
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
