Rough Cuts Now Available

by Subbu Allamaraju on September 5, 2009

A rough cuts version of this book is now available via Safari Online. See http://my.safaribooksonline.com/9780596809140. This is the first full draft of the book. Although the outline is more or less final, there are number of recipes that need to be refactored and rewritten. Your comments are very much appreciated.

{ 6 comments… read them below or add one }

Nick Floyd November 3, 2009 at 6:33 am

I noticed something on page 75. It refers to HTTP headers. My comment is regarding the “Content-Type” header field.

The way I have interpreted RFC2616 (sections 7.2.1, 14.17, and 14.1) content-type defines the body of the response from the server, where the accept header defines the body of the request from the client.

This is obscured by the comment in section 7.1 stating that: “…both sender and recipient refer to either the client or the server, depending on who sends and who receives the entity…”

However, the accept header’s responsibility is defined: “The Accept request-header field can be used to specify certain media types which are acceptable for the response.”

And section 17.14 defines the content-type as the: “…entity-header field indicates the media type of the entity-body sent to the recipient”

What are your thoughts on this? I’d love to know, this is something I have struggled to see clearly when building REST based APIs.

Reply

Mike Amundsen November 3, 2009 at 4:48 pm

Nick:

Keep in mind that the content-type header is passed by the client to the server when sending a body (POST, PUT). In those cases the client is the “sender.”

While content-type _does_ define the body of the response from the server, this is not an exclusive statement. The content-type also defines the body of the request from the client.

Reply

Nick Floyd November 4, 2009 at 1:55 pm

Mike:

Thanks for the reply and the solid perspective.

To make sure I understand, depending on the origin of the body:
sender=client POST, PUT – send Content-Type
sender=server GET, PUT, POST, DELETE – send Content-Type

Also, given:
sender=client GET – send Accept

Basically if there is a body involved (request or response) the originator is responsible for sending Content-Type

The above seems practical for simple resources, but what is done when you’re dealing with a thicker grained resource that has multiple custom media types (via HATEOAS).

So given the body is:

Nick

What would be the Content-Type? Even though it is clearly xml would you put text/xml or application/xml, or would the parent’s custom media type be used “application/vnd.domain.person_v1+xml”, etc…?

Thanks for the clarity and help.

Reply

Nick Floyd November 4, 2009 at 2:07 pm

Here’s the body:
<person id=”12″ uri=”http://domain/People/12″ type=”application/vnd.domain.person_v1+xml”>
<name>Nick</name>
<status id=”2″ uri=”https://domain/People/Statuses/2″ type=”application/vnd.domain.status_v2+xml”/>
</person>

As text:
[person id="12" uri="http://domain/People/12" type="application/vnd.domain.person_v1+xml]
[name]Nick[/name]
[statusid="2" uri="https://domain/People/Statuses/2" type="application/vnd.domain.status_v2+xml"/]
[person]

Reply

Nick Floyd November 4, 2009 at 2:12 pm

Here’s the body as text:
[person id="12" uri="http://domain/People/12" type="application/vnd.domain.person_v1+xml]
[name]Nick[/name]
[statusid="2" uri="https://domain/People/Statuses/2" type="application/vnd.domain.status_v2+xml"/]
[person]

Reply

Mike Amundsen November 4, 2009 at 3:09 pm

In the example you show, you’re asking how a server can communicate media-type information on supplied links to a client and (I assume) how a client can use that information when making a request.

First, there is no copmmon standard for this. HTML supports a “type” attribute for links, but browser clients treat this as a “hint” and do not alter their accept headers when activating these links. The XInclude standard introduced the “accept” attribute with instructions that clients SHOULD use this to modify their accept header when activating the link. I use this feature often, but it’s not a widely exposed feature of common clients.

Finally, the example you provide offers nothing in the way of the HTTP Methods that apply to the links. HTML, for example, uses GET for [a], [link], and [img] elements and allows users to control whether [form] elements use GET or POST. XInclude always uses GET.

I mention this last item to point out that the media-type represents more than a data format (JSON, XML, HTML). It also carries along it’s semantics – the rules for how to interpret the elements. These rules often include whether the link is valid for a particular method, the representation(s) allowed when sending a body and the representation(s) expected in a reply.

When authoring your own representations for your custom resources you may really be creating your own media type (format + schema + semantics). In that case, you need to include details of semantics somewhere, even if in the out-of-band documentation.

One option is to adopt a representation that communicates the semantics in other ways:

[person id="12" uri="..." rel="pdf" ]

Reply

Leave a Comment

Previous post:

Next post: