Menu
I am currently designing an enterprise service that is purely resource oriented. After reading several blogs, books, etc. I believe REST with Hypermedia links is the way to go.
However, one thing that all these blogs and books say is to not use application/xml as the media type when using the hypermedia links in the response. None of them say why except for a generic statement like - plain URIs with no link relation type do not communicate the semantics of URIs to clients.
From what I understood, it is a recommended approach to define your own custom media type and make the client aware of how to read it. But if it is known that the clients connecting to my service will never be browsers, does it matter? Can't I just expose these links in my response with application/xml type?
I was hoping someone here can elaborate more on this.
330
asked Apr 17 '13 18:04
The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text. REST architectural style lets us use the hypermedia links in the API response contents. It allows the client to dynamically navigate to the appropriate resources by traversing the hypermedia links.
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.
Hypermedia controls are the combinations of protocol methods and link relations in an hypermedia format that tells the client what state transitions are available and how to perform them.
Hypermedia is a way for the server to tell the client what HTTP requests the client might want to make in the future. It's a menu, provided by the server, from which the client is free to choose. The server knows what might happen, but the client decides what actually happens.
By using hypermedia in our responses we can offer links between API endpoints and documentation, potential actions, and related endpoints. This allows for discoverable APIs where it is clear from the API response the set of next actions that a client may want to take.
Custom media types are used in the API to let consumers choose the format of the data they wish to receive. This is done by adding one or more of the following types to the Accept header when you make a request. Media types are specific to resources, allowing them to change independently and support formats that other resources don't.
A good use case for using custom media type is versioning an API. 2. API – Version 1 Let's start with a simple example – an API exposing a single Resource by id. We're going to start with a Version 1 of the Resource we're exposing to the client. In order to do that, we're going to use a custom HTTP header – “application/vnd.baeldung.api.v1+json”.
This is because, the default media type is flexible and serves in most of the cases. However, having a Custom media type tightens the server and client contract by making them more tightly coupled. We can create custom media types, that are based on any other basic media types.
You don't have to use custom media types. In fact REST tries to discourage people from creating overly specific media types. The ideal is that media types should convey semantic information but not be specific to any particular service.
One problem with application/xml is that it has no standard definition for what a link looks like. Is it
<Link rel="foo" href="/foo">
or is it
<foo href="/foo">
or some other variant? How can your client know how to identify what links exist in a document without using "out of band" knowledge? "Out of band" knowledge is what you want to avoid because it is what causes clients to break when servers make changes and a client cannot protect itself against changes to out of band knowledge.
The other problem with application/xml is that it contains no semantics other than a hierarchy of elements and attributes. Semantics either have to be conveyed by a media type or a link relation. If you use application/xml then you have to use link relations to tell the client how to consume that document.
There can be a nice balance between conveying semantics in link relations and media types. But to be honest, the industry is trill trying to figure out exactly what that balance is and there are lots of people with different opinions on the subject.
I would suggest looking at application/hal+xml. It is the closest thing to generic XML but with link semantics defined.
67
Here is the best answer I can come up with... I've recently reached out to Dr. Fielding to validate my understanding, but have yet to receive a response. Should he yell at me, I will redact it.
I suspect that, as Darrel Miller has alluded to, the goal should be to avoid creating overly specific types - after all, it has been said:
A REST API should never have “typed” resources that are significant to the client.
I feel that most of the content of the internet regarding Hypermedia as it pertains to REST have essentially violated this principle and steers people in the wrong direction - because they introduce very specific "qualifiers" (as I will refer to them) to their resources.
You see things like application/vnd.com.foo.bar+xml or application/vnd.com.example.thing+json - some people have decided that rather than using the type itself, they will use parameters, e.g. application/xml; someKey=someValue -- this is, in my opinion, no different than qualification. This is, to me, a typed resource.
text/html is the epitome of hypertext for a reason - the browser has a processing directive that it uses to understand this media type. Not just rendering and layout, but robust interaction precedents are set by the HTML specification(s) (e.g. anchor tags cause retrieval, forms can trigger submission with encoding and so on) and it's for this reason that this very generic, highly powerful hypermedia type has allowed all the web pages we use today to come in to existence without any coupling between your browser and the server that provides them - the only thing necessary has been an understanding of what HTML, as a content-type, is.
What does this mean for APIs? It means that creating a content type specific for some resource, some specific URI (or set of them) isn't robustly using hypermedia and likely means you have the kind of client-server coupling that REST is trying to avoid. It also means that application/xml and the like are anemic - they have parsing directives but not processing directives. A well-designed REST API will have a much more generic hypermedia type, not created for a particular resource, but rather to clearly define the processing directives that potential clients must understand in order to participate.
The interesting - and admittedly probably controversial - thing is that text/html has a lot of that already - why not use it? The fact that our API consumers want something other than HTML (e.g. they think JSON or XML formats are a panacea) is really due to an inherent misunderstanding of what it means to have a hypermedia-driven application engine - namely it's that the processing directive of the representation should be rather generic. Granted, you can do this with XML, just by having your API define a clear set of elements and what they mean. The part about using HTML was just to illustrate a point.
Aspiring REST APIs, even with a rich set of hyperlinks expressing state transitions through resources, can - and it seems most often do - fall short of that extensible, long-living architectural style that REST is really about.
40
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
