MVC naming conventions for JSON actions

Question

What naming convention is recommended when writing an MVC app that has both front-end and JSON paths to the required data?

For example, let's say the user of your site has "Things". They should be able to go to a page to view their things, but we also need a way to pull those things back as JSON on other pages. I've been able to think of several options but I'm not keen enough on any of them to proceed. Here's what I've got:

1. /things/list for UI, /json/things for JSON - this would require a JsonController which would end up serving different kinds of objects, thereby defeating any chance of entity separation before we even start.
2. /things/list for UI, /things/list/json for JSON - probably my preferred option at the moment, but requires magic stringing (albeit just "json"). Also, if you also need a (string id) action signature for taking in some filter parameters or such, then you have the choice of adding an extra route or doing some dirty string splitting.
3. /account/mythings for UI, /things/list for JSON - a bit cleaner, but there might not always be a relevant controller that you could serve the "things" from. Plus, you're mixing entities again.

All and any suggestions welcome, thanks!

Answer 1

Arguably the path names could all be the same. You can examine the Accept header for the mime-type of your client's desired response, and then return an appropriate view based on what you find there:

• application/json: JSON View
• text/xml: XML View
• text/plain, text/html: JSP View

Browsers set this field to HTML; your JSON clients would simply set this field as appropriate.

Answer 2

It's highly unlikely that anyone would be bookmarking a URL that requests JSON so I think that it's not that important to keep the URL as clean. It's also likely to be programmatically generated, not hand entered. Given these, I'd consider adding it as a query parameter.

 /things/list  -- HTML
 /things/list?format=json  -- JSON

This won't break your URLs if you do have ID parameters or need other parameters as well. It could also work with POSTs as well as GETs.

/things/1  -- HTML for "thing 1"
/things/1?format=json -- JSON for "thing 1"

Answer 3

I use the convention of

/things/list -- HTML
/things/_listpage -- AJAX

The rule is that all AJAXed actions/views have a leading underscore. This tells me that they are never called top-level, and usually have no master page associated. In this case, I keep the action under the same controller in order to share any associated logic.

Typically in the list view I would have a

<% RenderAction("_listpage", "things", new {page = ViewData["CURRENT_PAGE"]}); %>