How to map different UI views in a RESTful web application?

Question

Hello,

I'm designing a web application, which will support both standard UIs (accessed via browsers) and a RESTful API (an XML/JSON-based web service). User agents will be able to differentiate between these by using different values in the Accept HTTP header.

The RESTful API will use the following URI structure (example for an "article" resource):

• GET /article/ - gets a list of articles
• POST /article/ - adds a new article
• PUT /article/{id} - updates an existing article based on {id}
• DELETE /article/{id} - deletes an existing article based on {id}

The UI part of the application will however need to support multiple views, for example:

• a standard resource view
• a view for submitting a new resource
• a view for editing an existing resource
• a view for deleting an existing resource (i.e. display delete confirmation)

Note that the latter three views are still accessed via GET, even though they are processed via overloaded POST.

---

Possible solution:
Introduce additional parameters (keywords) into URIs which would identify individual views - i.e. on top of the above, the application would support the following URIs (but only for Content-Type: text/html):

• GET /article/add - displays a form for adding a new article (fetched via GET, processed via POST)
• GET /article/123 - displays article 123 in "view" mode (fetched via GET)
• GET /article/123/edit - displays article 123 in "edit" mode (fetched via GET, processed via PUT overloaded as POST)
• GET /article/123/delete - displays "delete" confirmation for article 123 (fetched via GET, processed via DELETE overloaded as POST)

A better implementation of the above might be to put the add/edit/delete keywords into a GET parameter - since they do not change the resource we're working with, it might be better to keep the base URI same for all of them.

---

My question is:
How would you map the above URI structure to UIs served to the regular user, considering that there can be several views per each resource, please? Do you agree with the possible solution detailed above, or would you recommend a different approach based on your experience?

NB: we've already implemented an application which consists of a standalone RESTful API and a standalone web application. I'm currently looking into options for future projects where these two would be merged together (i.e. in order to reduce overhead).

Thank you,
M.

Answer 1

I'm not sure I see why you want to merge the two together; whilst the idea seems to make sense it I think it'll actually be a false economy.

A view is normally specific to the context of it's use. The fact that you have two different types of user (people and services) that both use the same channel (HTTP) shouldn't confuse that.

Having them seperate might seem like extra work now, but it'll be even more work when something happens in 4 months that means you need to split them apart again. Sepration of concerns goes beyond UI / Logic / Data.

As long as your logic is kept centrally, and is cohesive, then having two sets of views isn't an issue in my book.

As a compromise, can you kept the same URL structure for both views, but duplicated (i.e: consistent)?

Answer 2

In REST terms - the 'alternate views' are really just plain old resources because URIs are opaque. Relationships are discovered by following links from one to the other - in this case; from list of articles, to an article, to edit and delete that article. The key here is that it actually doesn't matter about your URI structure at all, i.e. the following are equally 'correct':

GET /article/123/edit
GET /article/123;edit

The answer really is just a matter of taste. Provided they are identified by a URI, and can therefore be linked to, then you are Doing It Right.

How would you map the above URI structure to UIs served to the regular user, considering that there can be several views per each resource?

I would do this in exactly the same way as the HTML application works - i.e by providing the same hyperlinks in XML so as to connect/link up the resources (views) for the client to follow and render in the UI as necessary.

e.g.

GET /article/foobar

200 OK
Content-Type: application/mytype+xml
....
<link rel="edit" href="/article/foobar;edit" />
....

lastly:

Do you agree with the possible solution detailed above, or would you recommend a different approach based on your experience?

I think your approach above is reasonable - however, you should definitely focus on link relations rather than URI patterns.

You could opt to keep things 'larger grained' and avoid separate delete (or even edit) resources for your XML driven application; simply by not linking to them in the XML and instead opting to include the delete/edit links and forms in the article resource itself - this would work fine alongside your initial proposal for the HTML driven version.

I general, the approach of using the same resources for the XML and HTML driven applications is a good one.