Return state transitions in response

[Greg Knapp]

Hi,

I just watched this video REST misconceptions, at 00:43 mins in the presenter proposes including state transitions in the links section.

http://www.infoq.com/presentations/rest-misconceptions

I don't disagree with this but was curious where the boundary is drawn about imparting API usage in the media type, my interpretation is to aim is to be as explicit as possible, to reduce assumptions by/embedding knowledge in clients.

In the above example, is it implied that these links are called via say PUT requests? If not, how do you convey the verb(s) to use for these links?

Does it even matter? Do you return HTTP 405 Method Not Allowed if an inappropriate verb is used? (makes for clumsy usage?)

Example taken from slide:

{
  "order": {
    "state": "received",
    "...": "...",
    "links": {
      {"rel": "cancel", "href": "http://..."},
      {"rel": "accept", "href": "http://..."},
      {"rel": "reject", "href": "http://..."}
    }
  }
}

Thanks, Greg

[Kijana Woodard]

It depends on the hypermedia format.

For Hal, you read the docs found at the rel endpoint.

For other formats, the verbs are made explicit [Mason, Siren, etc]

There are pros/cons to both approaches which you can find in the archives of this forum.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[sgoto]

Good question. I went through this dilemma too, let me try to share what we converged to.

FWIW, schema.org actions's design is to send back to clients the *semantics* (e.g. cancel, accept, reject) as well as the *mechanisms* (e.g. whether to use GET or PUT). 

Here is one concrete example of how that appears in gmail:

https://developers.google.com/gmail/markup/reference/rsvp-action

So, to answer your question, I think you should do the latter: send back to clients the HTTP verb to use, rather than forcing your clients* to "read" documentation.

* in my specific case, "client" here means "google". that is, it wouldn't scale for google to read everybody's API's documentation to know which HTTP verb to use, nor to enforce that at the semantical verb level. it has to be told what to do.

 

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

--

f u cn rd ths u cn b a gd prgmr !