Where to put forms / alternative views in a RESTful html app?

forms, html, rest

Solution

You have a website like, the one way to build a real RESTFull API is to split the frontend and the API - thats in my opinion the best way (some may disagree) - maybe some other don't think like this but lets say the frontend team got `www.domain` and your team for the API got `api.domain`.

GET api.domain/questions - Retrieves a list of tickets   
GET api.domain/questions/12 - Retrieves a specific ticket   
POST api.domain/questions - Creates a new ticket  
PUT api.domain/questions/12 - Updates ticket #12  
DELETE api.domain/questions/12 - Deletes ticket #12  
PATCH api.domain/questions/12 - Partially updates ticket #12 #I only want to display that this also exists - i don't really use it...

AWESOME EDIT: As you can see also stackoverflow uses this method: api.stackexchange.com

So as you can see you can have these structure - but you also can have a form on `www.domain/questions/ask` and this form would send the request to `api.domain/questions` via `POST`. I want to refer to: https://thenewcircle.com/s/post/1221/designing_a_beautiful_rest_json_api_video its a really nice podcast you should have heard.

EDIT: (another point of view)

Another idea is that you can simply choose which content should come back (Json,XML,HTML) if your client sends you the right Accept-Header.

Example 1:

       URL           REQUEST       ACCEPT HEADER               RESPONSE                      
-----------------------------------------------------------------------------------------
domain/questions      GET        application/json   all questions as json
domain/questions      GET        text/html          the page as html with all questions
domain/questions/ask  GET        text/html          Your html for to add a new question
domain/questions      POST       application/json   Add a new new questions (this would be called from ./ask to add the new questions
domain/questions/ask  GET        application/json   404 Status-Code because on questions/ask you don't have implemented any resource

Example-2:

       URL              REQUEST     ACCEPT HEADER               RESPONSE                      
-----------------------------------------------------------------------------------------
domain/questions/12       GET      application/json   Shows the questions with the ID 12 as JSON
domain/questions/12       GET      text/html          Shows the HTML representation of your page
domain/questions/12/edit  GET      text/html          Your html for to edit a the question
domain/questions/12       PUT      application/json   Updates the questions with the ID 12 // just to add the PATCH thing.. i don't really use it but if you don't update the whole object you could/should use PATCH instead of PUT :p
domain/questions/12/edit  GET      application/json   404 Status-Code because on questions/ask you don't have implemented any resource

Yesterday I told you about the first idea (which is - I think for using an api as a team (one for frontend and one team that develops the api - a better way) but as @jackweirdy commented (thanks for that - i then searched a lot and was looking at other podcasts from developer around the world and how they would do that) below it's really all up to you - it's your api and at the end you/your team will decide for one way. Hope this helps you or other that looking for how to build a API on a REST background.

The examples in the EDIT-Section would be (if I got it right) not like here on stackoverflow

Problem

Let's assume an web application that for each URI presents a nice html view for GET requests and allows to update the underlying resource through POST/PUT/PATCH/WHATEVER. How do I then expose various forms that actually allow performing such requests from the browser? And broader: assuming I have alternative views (possibly also HTML) for the same resource, where do I put those? Arguably, such forms can be considered alternative views, so having an answer to the broader question would be ideal. Edit: To clarify, my question is not about pure data APIs serving JSON or whatnot, but about HTML apps such as Stackoverflow. For example you can get the collection of questions under `/questions` and this particular one at `/questions/24696982` which makes sense. To get the form to add a new question, you will have to use `/questions/ask`, which I'm not sure is alright. And that form POSTs to `/questions/ask/submit`, which seems just plain wrong. Making a GET request to that URL yields a 404 (if anything it should be a 405). The form should be POSTing to `/questions`. Still I would like to know whether at least the URI for the form is considered acceptable in a RESTful system.

Original source