Updated: Comment #47
Problem/Motivation
Currently, REST module creates all entity routes at /entity/{type}/{id}. That rarely matches the HTML-based route. They should match, to be properly RESTful. Example: JSON representations of nodes should be available at /node/1, not /entity/node/1.
Proposed resolution
Now that NG entities can define their own link relations per #1970360: Entities should define URI templates and standard links , we can just leverage that. To wit:
1) The URI for an entity should be the "canonical" link the entity defines.
2) We have to create a new link relation to specify the URL path where to create new entities. The current proposal for the name is "http:/drupal.org/link-relations/create", a fully qualified domain name. Example: /node would be the link for POSTing a new node. This is the most reasonable thing we can do for now until we settle on a solution how we deal with link relations in general. This is discussed in #2113345: Do not use link relations as keys for entity links annotation
and does not block this issue.
3) We have to split up MimeTypeMatcher into AcceptHeaderMatcher and ContentTypeHeaderMatcher in order to be able to differentiate properly between POST requests to the same path that carry form data vs. JSON or other formats. Example: POST to /node with Content-type: application/hal+json should not end up on some node/view HTML route.
4) We have to initialize the _method restriction on routes to GET|POST so that other routes with different HTTP methods have a chance to be matched. Example: a DELETE request to /node/1 should not end up on the usual node view HTML route.
Remaining tasks
* Commit the RTBC patch.
User interface changes
None.
API changes
Entity URIs for web services change to what they should be anyway. Example: /entity/user/1 changes to /user/1.
Related Issues
#1970360: Entities should define URI templates and standard links
#2113345: Do not use link relations as keys for entity links annotation
Steps to make this manually testable
There is lots of documentation on all the REST stuff here: https://drupal.org/documentation/modules/rest
Here's the quick way to get you started on making REST requests:
- Enable modules rest and hal
- Set permission "Access GET on Content resource" for anonymous users.
- Get a REST Client (there's for example a firefox called RESTClient)
- Create a node for testing
- Make /node/$nid GET request with the "Accept: application/hal+json" set