rest/rails: Difference between revisions
BradGessler (talk | contribs) |
|||
(5 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
''' | <div style="border: 1px solid #069; padding: 1em; margin: 1em 0;">'''All of the old stuff in this article that has been implemented in Rails has been cleaned out. This article should NOT be considered obsolete.'''</div> | ||
= Participants = | = Participants = | ||
* David Hansson | * David Hansson | ||
* Dan Kubb | * Dan Kubb | ||
* Ernest Prabhakar | * Ernest Prabhakar | ||
* | * [http://www.bradgessler.com/ Brad Gessler] | ||
= Wish List = | = Wish List = | ||
Line 350: | Line 230: | ||
Also, for the case of "Autocomplete" lists, the JSON or XML may have to be embedded into some sort of HTML template so that the list can be styled appropriately. These might be specified as templates, which are proposed above. | Also, for the case of "Autocomplete" lists, the JSON or XML may have to be embedded into some sort of HTML template so that the list can be styled appropriately. These might be specified as templates, which are proposed above. | ||
== Globaly Unique XML/JSON ID == | |||
Currently in RESTful rails, the IDs of XML/JSON objects are the IDs as they appear in the database. For example, | |||
<pre> | |||
<poll> | |||
<created-at type="datetime">2007-07-02T11:13:46-07:00</created-at> | |||
<id type="integer">29</id> | |||
<multivote type="boolean">false</multivote> | |||
<permalink>LTMxNDk5MTc2MQ</permalink> | |||
<question>What Would Tyler Durdon Do?</question> | |||
<updated-at type="datetime">2007-10-08T13:53:11-07:00</updated-at> | |||
<user-id type="integer">1</user-id> | |||
<is-open type="boolean">false</is-open> | |||
<total-results-count type="integer">1</total-results-count> | |||
</poll> | |||
</pre> | |||
The ID should instead refer to the globally unique HTTP location of the resource, not its primary key ID in the database. The above representation should instead appear as: | |||
<pre> | |||
<poll href="http://www.polleverywhere.com/polls/LTMxNDk5MTc2MQ.xml"> | |||
<created-at type="datetime">2007-07-02T11:13:46-07:00</created-at> | |||
<multivote type="boolean">false</multivote> | |||
<question>What Would Tyler Durdon Do?</question> | |||
<updated-at type="datetime">2007-10-08T13:53:11-07:00</updated-at> | |||
<user-id type="integer">1</user-id> | |||
<is-open type="boolean">false</is-open> | |||
<total-results-count type="integer">1</total-results-count> | |||
</poll> | |||
</pre> | |||
Note the ''href'' is the unique identifier for the poll. This would be advantageous when displaying a list of larger datasets. The list could contain many href to the more complete representations. The client could then directly follow the URL rather than placing the burden of URL construction on the consuming application. Also, this makes the possibility of breaking the client side application less likely since it doesn't have to understand how to plug the ID column into a URL; instead, it can just directly access the URL. | |||
== Examples (TBD) == | == Examples (TBD) == |
Latest revision as of 13:43, 11 October 2017
Participants
- David Hansson
- Dan Kubb
- Ernest Prabhakar
- Brad Gessler
Wish List
[Portions may be obsoleted due to above plug-ins solving these problems differently]
While nominally focused on specific feature requests to add to Rails, in fact many of these recommendations are also relevant for other frameowrks, and even general "REX".
Columns as class names
In addition to 'human_readable' column names, I'd like there to be a parameter for the equivalent 'css-friendly' representation of those columns -- and for the default templates to include that.
Complete, functioning, customizable web application
I want to be able to do something like:
$ script/generate rex modelA modelB
And get a full-blown web application which includes:
- the front page, including navigation links to various model objects.
- search boxes
- entry forms
- AHAH (ajax) responses
- both list- and table- oriented model representations
The ideal is that I could use a combination of CSS and AHAH to generate the desired look, feel, and behavior of my website without actually having to touch existing HTML. As a bonus, I also want it complete enough that I can write a REST-spider to easily discover all the valid URIs and queries. Hey, a guy can dream...
OPTIONS Handling
The controller should be able to handle OPTIONS requests and know what specific methods it can handle for a given URI.
Output Content Negotiation
It would be nice to be able to have the view look at the Accept headers and choose the best template to output.
For example, imagine you had the following files:
- index.rhtml
- index.rxml
- index.rtxt
If the browser sent the Accept as text/html then the index.rhtml would be used. For text/plain the index.rtxt would be used, and so on.
If there was a way for a view handler to "register" itself and say what mime types it knows how to handle, then the optimal handler could be chosen at runtime. The handlers could do anything they want in order to output the response body, including using libraries like GD.
Input Content Negotiation
When a request has a body, it needs to be parsed and stored into the request parameters. Rails handles normal web forms and multi-part form input.. but it would be nice to be able to write custom handlers that knows how to parse requests for specific mime-types and set the appropriate request parameters inside rails.
This would allow you to POST a web form or a yaml string and have the values funneled into the same parameters -- your controller wouldn't care where the data is come from. I realize yaml is supported by rails natively, but it should be possible to register handlers for any other mime types.
Perl's Catalyst MVC is starting to do this with their HTTP::Body module.. they made it so you can write custom modules to parse any mime-types and set the request parameters.
HEAD responses
Responses to HEAD requests should be identical to GET requests, minus the body. Rails should omit sending the body for HEAD requests, but still send all the appropriate headers. Its especially important that the Content-Length be the same for HEAD and GET responses.
Conditional GET requests
When writing mod_perl handlers I was able to do something equivalent to:
def get_index # do some work to set up @resource set_etag @resource.digest_hash set_last_modified @resource.updated_at return not_modified if conditional_get? render end
This resulted in a snappier response from some apps since it didn't require a full transfer if it was not modified since my last request.
AJAX apps to use HTTP more fully
Most Rails AJAX apps use only GET and POST, but they should be encouraged to use the full set of HTTP verbs in examples.
Encouragement of Conditional GET in AJAX apps would be a bonus as well.
Proposal
As proposed on April 1st by Charlie Savage, in response to Dan Kubb's architecture for [#RESTful Rails]
Syntax
The currently proposed syntax is:
resource :collection do |r| r.post do end end
Where 'r' is an instance of a Resource class. At first I preferred a simpler syntax, like this:
resource :collection do method.post do end end
Where method represents the HTTP verb (GET, POST, PUT)? Or maybe even:
resource :collection do request.post? do end end
However, do you have to have an instance of the resource class to achieve the 4 points you brought up (more details in original email):
- Handling OPTIONS requests.
- Returning 405 when appropriate
- Return 501 when appropriate
- Checking If-* request
These all would be good features to have. If they require having a resource class passed as "r" then I can agree to this approach.
Templates
You mentioned that you'd expect these responses for different methods:
- GET - 200 OK
- Response Body
- POST - 303 See Other
- No Response Body, Location header to newly created resource
- PUT - 303 See Other
- No Response Body, Location header to resource
- DELETE - 303 See Other
- No Response Body, Location header to collection resource
Using regular HTML forms I'd agree. However, this breaks down when using XmlHttpRequest. For example, if I do a post and it fails and I want to return an error message. Doing a redirect is a bit silly since the URL in the browser address bar isn't going to change anyway - its easier to just return the result from the POST. Same is true for a PUT, whether an update is successful or not. Thus, I think we must provide a system where you can provide a response body regardless of the method. One approach is Peter's proposal of just using a standardized directory structure:
view my_controller resource1 get put resource2 post delete
I like this concept. However, maybe it would be confusing since Rails uses directories for nested classes (MyNamespace::MySubNamespace::MyController). Thus, we could go use the name mangling I currently do now, i.e., get_resource1, or resource1_get (which I like better because it groups the templates for a resource together a bit more clearly).
Editors
We seem to be in complete agreement. I.E:
- /book/1
- Viewable representation of book #1 retrieved by GET
- /book/1/editor
- Editable representation of book #1, will PUT to /book/1
- /book/creator
- Form to create a new book, will POST to /book
Top Level Resources
Here is something Peter and I disagree about. Do you prefer this style:
Option #1
def MyController resource :collection do |r| ... end resource :member do |r| ... end resource :editor do |r| ... end end
Option #2
Or this:
def MyController r.get ... end r.post ... end resource :member do |r| ... end resource :editor do |r| ... end end
The difference being in the first case you insist every resource must be defined via "resource" while in the second you say that the controller is the top level resource. When I first did my RestController I went with option #1 because it seemed more elegant. However, I quickly changed my mind when actually writing code because it turned out to be annoying having to add the extra syntax. This was particularly true for controllers that are just single resources. For example, say you have geocoding functionality so you have a GeocoderController. It does just one thing, GETs geocoding results so there is no concept of collection/member. Thus I favor option #2 as a syntax shortcut.
Caching
Sounds like we've agreed that caching is important, but is not part of the Rest Controller. Thus, you'll split that off the caching functionality into another plugin that can work with a Rest Controller.
Implementation
I see that your implementation is significantly different than mine. I map :resource to a Ruby module, which gets included in a controller. In contrast, you map :resource to a Ruby method. Within that method you create an instance of a Ruby class called Resource and then execute the provided block in its context.
This disadvantage of my approach is that there is method renaming that goes on under the scenes, which you have to know about in order to get filters to work correctly. The disadvantage I see to your implementation is that all the methods for a resource get mapped under a single Ruby method. It seems that would make it hard to apply filters to specific methods. I.E., how could I apply a filter to a GET method of the resource Member but not to the POST? It would be great if we could use the existing filter syntax without change, but I'm guessing that might not be reasonable because now we are dealing with Resources and Methods as opposed to Actions. Anyway, this is something I think is important to solve.
Also, how does your Rest controller interact with the base ActionController? I'm not seeing it being include anywhere...could you point me to the appropriate code.
Filtering
XML and JSON should be filterable at the URL level. For example, if I am implementing an AJAX autocomplete list, I only need the ID column and the display value field from the server. I also would have to specify a "filter" string to narrow the result set scope. This could be done by:
http://host.com/models.json?filter=value&fields=id,display_name&start=0&limit=100
The URL breakdown
- filter (string)
- A string passed to the application to search for, or filter results
- fields (string)
- The fields that should be returned for the query. In this case, both the ID and display_name field.
- start (integer)
- The position where the results of the records begin
- limit (integer)
- Limits the results to the specified amount.
Some of these may be a bit too 'database' specific, so I would be interested in finding the right nomenclature to generalize this a bit more.
Also, for the case of "Autocomplete" lists, the JSON or XML may have to be embedded into some sort of HTML template so that the list can be styled appropriately. These might be specified as templates, which are proposed above.
Globaly Unique XML/JSON ID
Currently in RESTful rails, the IDs of XML/JSON objects are the IDs as they appear in the database. For example,
<poll> <created-at type="datetime">2007-07-02T11:13:46-07:00</created-at> <id type="integer">29</id> <multivote type="boolean">false</multivote> <permalink>LTMxNDk5MTc2MQ</permalink> <question>What Would Tyler Durdon Do?</question> <updated-at type="datetime">2007-10-08T13:53:11-07:00</updated-at> <user-id type="integer">1</user-id> <is-open type="boolean">false</is-open> <total-results-count type="integer">1</total-results-count> </poll>
The ID should instead refer to the globally unique HTTP location of the resource, not its primary key ID in the database. The above representation should instead appear as:
<poll href="http://www.polleverywhere.com/polls/LTMxNDk5MTc2MQ.xml"> <created-at type="datetime">2007-07-02T11:13:46-07:00</created-at> <multivote type="boolean">false</multivote> <question>What Would Tyler Durdon Do?</question> <updated-at type="datetime">2007-10-08T13:53:11-07:00</updated-at> <user-id type="integer">1</user-id> <is-open type="boolean">false</is-open> <total-results-count type="integer">1</total-results-count> </poll>
Note the href is the unique identifier for the poll. This would be advantageous when displaying a list of larger datasets. The list could contain many href to the more complete representations. The client could then directly follow the URL rather than placing the burden of URL construction on the consuming application. Also, this makes the possibility of breaking the client side application less likely since it doesn't have to understand how to plug the ID column into a URL; instead, it can just directly access the URL.
Examples (TBD)
Last, it would be good to have an example controller for people to play with. Something simple, like a ProductController or maybe copying one of the examples from the Agile Web Development book.
- Dan Kubb's XML.com article: http://www.xml.com/lpt/a/2006/04/19/rest-on-rails.html