How do you implement resource "edit" forms in a RESTful way?

Question

We are trying to implement a REST API for an application we have now. We want to expose read/write capabilities for various resources using the REST API. How do we implement the "form" part of this? I get how to expose "read" of our data by creating RESTful URLs that essentially function as method calls and return the data:

GET /restapi/myobject?param=object-id-maybe

...and an XML document representing some data structure is returned. Fine.

But, normally, in a web application, an "edit" would involve two requests: one to load the current version of the resources and populate the form with that data, and one to post the modified data back.

But I don't get how you would do the same thing with HTTP methods that REST is sort of mapped to. It's a PUT, right? Can someone explain this?

(Additional consideration: The UI would be primarily done with AJAX)

-- Update: That definitely helps. But, I am still a bit confused about the server side? Obviously, I am not simply dealing with files here. On the server, the code that answers the requests should be filtering the request method to determine what to do with it? Is that the "switch" between reads and writes?

score 12 · Answer 1 · edited Sep 03 '16 at 17:49

There are many different alternatives you can use. A good solution is provided at the microformats wiki and has also been referenced by the RESTful JSON crew. As close as you can get to a standard, really.

 Operate on a Record

GET /people/1
    return the first record 
DELETE /people/1
    destroy the first record 
POST /people/1?_method=DELETE
    alias for DELETE, to compensate for browser limitations 

GET /people/1/edit
    return a form to edit the first record 
PUT /people/1
    submit fields for updating the first record 
POST /people/1?_method=PUT
    alias for PUT, to compensate for browser limitations

I believe `?_method=XXX` is what Spring's form JSP taglib does. — Raedwald, Aug 28 '12 at 21:42

score 4 · Answer 2 · answered Sep 05 '08 at 15:36

4

I think you need to separate data services from web UI. When providing data services, a RESTful system is entirely appropriate, including the use of verbs that browsers can't support (like PUT and DELETE).

When describing a UI, I think most people confuse "RESTful" with "nice, predictable URLs". I wouldn't be all that worried about a purely RESTful URL syntax when you're describing web UI.

answered Sep 05 '08 at 15:36

Brad Wilson

67,914
9
74
83

2

Too many people seem to try to force "restful" urls into websites when it better applies to web services. – Matthew Manela Aug 13 '09 at 03:16
Is this what your mean: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post – Raedwald Aug 28 '12 at 21:43

Mark Cidade · Accepted Answer · 2008-09-05T15:23:03.327

3

If you're submitting the data via plain HTML, you're restricted to doing a POST based form. The URI that the POST request is sent to should not be the URI for the resource being modified. You should either POST to a collection resource that ADDs a newly created resource each time (with the URI for the new resource in the Location header and a 202 status code) or POST to an updater resource that updates a resource with a supplied URI in the request's content (or custom header).

If you're using an XmlHttpRequest object, you can set the method to PUT and submit the data to the resource's URI. This can also work with empty forms if the server supplies a valid URI for the yet-nonexistent resource. The first PUT would create the resource (returning 202). Subsequent PUTs will either do nothing if it's the same data or modify the existing resource (in either case a 200 is returned unless an error occurs).

edited Sep 05 '08 at 15:23

answered Sep 05 '08 at 15:17

Mark Cidade

98,437
31
224
236

1

I disagree that the POST request should not be made to the resource to be edited. I say it should be made there and nowhere else. You are saying "hey, resource, do something with this data". At least that way you are getting 50% of the semantics right, and agents involved may realise their caches of the resource might need updating. By sending the POST request to another 'updater' resource, you miss out on that. That POST To Collection is often mapped to CRUD's create is just due to the limitation that HTTP has no CREATESUBRESOURCE method, and POST is the fallback, catch-all method. – Nicholas Shanks Nov 28 '12 at 15:15
1

The POST method ___is___ the CREATESUBRESOURCE method, See http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 — "The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database." – Mark Cidade Nov 28 '12 at 20:25
but modern POST usage contains no creation semantics (unlike it's NNTP forebear, and the method's original intent). my point though was mostly about creating an additional resource to handle updates to resources somewhere else in the URI space. i.e. good: POST /resource action=patch but bad: POST /updater-script resource=/resource&action=patch – Nicholas Shanks Nov 29 '12 at 10:58

score 0 · Answer 4 · answered Sep 05 '08 at 15:16

The load should just be a normal GET request, and the saving of new data should be a POST to the URL which currently has the data...

For example, load the current data from http://www.example.com/record/matt-s-example and then, change the data, and POST back to the same URL with the new data.

A PUT request could be used when creating a new record (i.e. PUT the data at a URL which doesn't currently exist), but in practice just POSTing is probably a better approach to get started with.

How do you implement resource "edit" forms in a RESTful way?

4 Answers4

Linked