suggest changes to itemset interface

[joshbronson]

Currently we send the following methods to /v1//itemsets//

fetch: GET
update: PATCH with payload {"contents" : }
create: PUT with payload {"contents" : }
remove: DELETE with payload {"contents" : }

Unfortunately, DELETE is not meant to accept a payload, and Java actually rejects it with an exception. It's meant to destroy something created by PUT. Furthermore, PATCH is mentioned in the latest (1999) HTTP spec, but it appears to have been removed there despite its recent (2012) resurgence in popularity. Goliath does not support it and may never support it.

Therefore, I propose the following protocol:

fetch: GET
update: POST /_update with payload {"contents" : }
create: PUT with payload {"contents" : }
remove: POST /_remove with payload {"contents" : }

We used PATCH because it's exactly what we wanted and because it's require to be idempotent. There's nothing requiring POST not to be idempotent, however, so I think we're good.

[mrflip]

• PATCH: look at the way rails does it; it's a POST having a certain header
  or query string, and handled in middleware.

  Forms of persisted resources get "patch" in the hidden field "_method".
  The RFC is deliberately vague about the way to represent changes in a PATCH
  request. Submitting a form is perfectly valid, client and server must
  simply agree on the accepted ways to update a resource.
  Let me emphasize that the "_method" hack is a workaround for the
  limitations in web browsers. As you probably know Rails routes real HTTP
  methods. That is, actual PUT, DELETE, and now, PATCH requests are routed to
  their respective actions.

  Direct clients can handle the method fine; it's browsers that need the
  hack. The Goliath middleware should be pretty straightforward.

• does it work to make DELETE be DELETE with .../id (append the ID of the
  resource to the URL)? That would be the restful-ish way to do it.

flip

On Thu, Mar 7, 2013 at 6:36 PM, joshbronson notifications@github.comwrote:

Currently we send the following methods to /v1//itemsets//

fetch: GET
update: PATCH with payload {"contents" : }
create: PUT with payload {"contents" : }
remove: DELETE with payload {"contents" : }

Unfortunately, DELETE is not meant to accept a payload, and Java actually
rejects it with an exception. It's meant to destroy something created by
PUT. Furthermore, PATCH is mentioned in the latest (1999) HTTP spec, but it
appears to have been removed there despite its recent (2012) resurgence in
popularity. Goliath does not support it and may never support it.

Therefore, I propose the following protocol:

fetch: GET
update: POST /_update with payload {"contents" : }
create: PUT with payload {"contents" : }
remove: POST /_remove with payload {"contents" : }

We used PATCH because it's exactly what we wanted and because it's require
to be idempotent. There's nothing requiring POST not to be idempotent,
however, so I think we're good.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/4
.