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?

Answer 1

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.

Answer 2

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).

Answer 3

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.

Answer 4

This is good information. But I think I am still fuzzy on the server implementation. Can we get more concrete?

Assume that I am working with some kind of controller or dispatcher (or whatever) on the server side that actually responds to these HTTP requests (language is unimportant, really). You're saying that if the GET request comes in for...

GET /restapi/edit-myobject

...I know to return the XML for that object's properties to be included in the form? So, in this case the URL itself is very much like a method (not just a resource), because I not just using the HTTP "verbs". Or, is it more like...

GET /restapi/myobject

...and I know simply because of the HTTP method GET that this is a "read" of the "myobject"?

So, on the "write" then, we would just have...

POST /restapi/myobject

...and the "controller" would dispatch the request differently because of the POST, possibly doing an update in the DB or whatever. Is that what you mean?

Answer 5

Obviously 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