What is the proper media-type for HAL+JSON?

Question

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!

Apace

what do you mean by "wild-card type"? – Tobey

@JulianReschke A wild-card type is something like application/*+json – Apace

I got that; but where do you want to use it? Don't say in "Accept:". – Tobey

@JulianReschke Oh lord, not in Accept:! It's for the media-type converter that handles mapping incoming JSON to DTO's (and vice-versa). – Apace

Answer 1

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.

Armstead

That makes sense and that was the direction I was going in as well. application/blah+hal+json didn't make sense to me. Also, yes in the API my entities have the possibility for HAL to be included. – Apace