How do I define an edit page within a REST API?

Question

In a Play app I'm designing, these are some of my routes

POST    /visits                     controllers.Visit.create
GET     /visits                     controllers.Visit.visits
GET     /visits/:id                 controllers.Visit.visit(id: Long)
PUT     /visits/:id                 controllers.Visit.update(id: Long)
DELETE  /visits/:id                 controllers.Visit.delete(id: Long)

I'm supporting a browser interface too. I'm following with the guidance I saw here: RESTful on Play! framework

I can easily provide an HTML template to display detailed information about one specific visit, or a list of visits. But how does an "edit page" fall cleanly into this, which would have to be prefilled with the information from a particular visit? I can easily do something like: GET /visits/:id/edit controllers.Visit.edit(id: Long) which would return a prefilled page with the visit information, or I can have a static HTML page which calls the /visits/:id with an AJAX call to populate the fields, and this would let me avoid corrupting my resource-driven API with a browser page-specific route. Or is there some better option? What is best practice and why?

Answer 1

In REST it doesn't make sense for you to create additional resources simply to perform standardized actions. Everyone who knows the HTTP protocol knows your visit object should be editable through a PATCH request with the diff you want to be applied, or through a PUT request that replaces the whole resource with a new one. Why create a custom and non-standard edit action with POST, that you will have to document and explain to everyone how it works?

In that sense, I'd say your best option is having a static HTML page that drives your API, using a GET on /visits/:id to populate the fields, and use the edited content to replace /visits/:id with a PUT when submitted.

However, keep in mind that there's nothing wrong with having a browser page-specific route in your API, as long as you're respecting the Accept header sent by the client. On my APIs, I sometimes have some routes returning a human friendly representation of the resource when the request is made using the Accept: text/html header, so it's a simple way to have a builtin admin client and the API can be easily explored with a browser. In REST, the only difference between an API and a WEB page is that the first returns a representation in a machine-friendly format, and the second a representation that you expect to be rendered by a browser in a human-friendly document. Both of them are supposed to have the links and/or forms with directions on how to edit the resource.