note down differences in PUT, POST and PATCH

[rstacruz]

it'd be great to mention that POST is typically used for creating things (POST /articles), and PUT/PATCH for editing (PUT /articles/123).

[geemus]

Would you be up for taking a first pass at this? It could probably fit in the Requests section and be structured similar to the status codes stuff in Responses (ie a bulleted list). I'm happy to take it from there and flesh it out, but would definitely welcome contribution as well. Thanks!

[creynders]

@geemus I had a look at the heroku platform API and noticed that you're supporting the wide-spread (wrong?) use of PATCH as a partial resource update action, instead of how it's described in RFC 5789

with PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.

Is this deliberate? And if so, why? Or am I misinterpreting the spec?

[creynders]

Of course only seconds after posting I found this: http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10

A spec on how to describe PATCH operations through JSON API's. E.g.:

 { "op": "replace", "path": "/a/b/c", "value": 42 }

The path key is maybe a bit ill chosen, it

references a location within the target document

Anyway, converting an example from the heroku docs would make it:

$ curl -n -X PATCH https://api.heroku.com/account \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Content-Type: application/json" \
-d '{
  "op": "replace", "path": "email", "value": "username@example.com"
}'

[creynders]

And sorry for hijacking this thread, but come to think of it, this would mean the actions part could be described entirely using PATCH instead.

[geemus]

@creynders - I can certainly see what you are getting at. In our case, we just wanted partial update. ie we simplify the usage a bit through the assumption that you ALWAYS want to do replace ops and you are just specifying key/value. I think this is still in the spirit of the RFC, though one could argue we should be using a special media type that better defines these expectations. ie we just have a much simpler/more naive patch document format than say json-patch.

I don't think this would be sufficient to accomodate actions as those are more likely to be things like start/stop/transfer, etc. ie things that are more complex than modifying a particular attribute value, which I think is the scope of capability afforded to json-patch.

Hope that helps clarify a bit, but certainly happy to further discuss.