CODEWITHSUNDEEP
htmlrest
Mark Unwin
Mark Unwin

Reputation: 1623

Restful design pattern for HTML

I am trying to stick to the Restful design pattern for both JSON and HTML. My issue is the design for creating a new resource (amongst others, but this is the gist of the issue). IE:

JSON – POST to /resource creates a new resource.
JSON – GET to /resource returns a list of resources.
JSON – GET to /resource/{id} returns a resource.
HTML – POST to /resource creates a new resource.
HTML – GET to /resource returns a list of resources.
HTML – GET to /resource/{id} returns a resource.

All good so far – but I need a HTML form to actually create the data to send to the HTML POST. Obviously POST and GET already do things. I could use one of the below to return the HTML form:

HTML – GET to /resource?CREATE
HTML - GET to /resource?action=CREATE
HTML – GET to /resources/CREATE

But they seem like a kludge and not that intuitive. Any thoughts or ideas?

EDIT - See my answer to my question below. At present this is (I consider) the best option.

Upvotes: 2

Views: 122

Answers (4)

Opal
Opal

Reputation: 84874

I'd rather add and endpoint called /templates/ that returns a template/form/whatever you need for given action. It also seems that the server should be unaware of such form existence. It can accept or reject a request and it's client job to submit it in an appropriate format.

I guess that you mix processing the view with preparing RESTful endpoints. The backend site should be completely unaware of the fact that some sort of view/form is required. It's client job to prepare such form.

Upvotes: 0

Mark Unwin
Mark Unwin

Reputation: 1623

I have an answer. I'll use standard RESTful POST from a HTML page, but when I have no form parameters sent and my accept header is text/html, I'll send a HTML form to the requestor. Keeps RESTful URI design and allows a clean HTML form + process (2 step).

HTML - POST - /resources (with no form attributes) generates a HTML form
HTML - POST - /resources (with form attributes) adds a resource
JSON - POST - /resources (with form attributes) adds a resource

OK, it's not "strictly" RESTful as I'm POSTing but not creating a new resource so in theory I should use a GET for that, but it's the best of a mismatched design.

If anyone can provide a better solution, I'm still all ears :-)

Upvotes: 0

Thierry Templier
Thierry Templier

Reputation: 202326

In fact, you should leverage content negotiation (CONNEG) when you want to handle several formats within RESTful services.

I mean:

  • Set the Content-Type header to specify the type of sent data
  • Set the Accept header to specify the type of data you want to receive

The server resources should leverage these hints to make the appropriate data conversion.

In the case of JSON, the content type would be obviously application/json. For HTML form, you should leverage the content type application/x-www-form-urlencoded (or multipart/form-data if you want to upload files as well). See the specification for more details.

Otherwise, you shouldn't use action in URL since it's not really RESTful. The HTTP verb should determine the action to do on the resource. I mean, to create a resource, the POST method should be used. The GET method aims to retrieve the state of a resource.

For more details, you could have a look at this blog post:

Upvotes: 0

Jeroen Noten
Jeroen Noten

Reputation: 3634

I would indeed use something like /resources/create. If you want to allow for non-numeric identifiers, then this will not work. In that case you can identify a resource with a prefix, such as /resources/resource-{id} and then you can still use /resources/create.

I found this blog post really helpful to make URI scheme decisions: http://blog.2partsmagic.com/restful-uri-design/

Upvotes: 1

Related Questions