Skip to content

Resources

dscape edited this page · 4 revisions

Resources

It's often the case when you want to perform all CRUD (Create, Read, Update, Delete) actions on a single resource, e.g. you want to create, read, update and delete users. RESTful architectures normally map those actions to HTTP verbs such as GET, PUT, POST and DELETE. Dynamic Resources are available but uncommon - if you are thinking about it you are probably looking for a singular dynamic resource. Please check the wiki page on Dynamic Paths for more information.

When you create a resource in rewrite you expose these actions:

Verb Path Action Notes Default Mapping
GET /users index Displays a list of all users /resource/users.xqy?action=index
GET /users/:id get Display information about a specific user /resource/users.xqy?action=get&id=:id
PUT /users/:id put Creates or updates a user /resource/users.xqy?action=put&id=:id
DELETE /users/:id delete Deletes a user /resource/users.xqy?action=delete&id=:id
POST /users post No special meaning /resource/users.xqy?action=post
GET /users/new new Return a form for creating a user. /resource/users.xqy?action=new
GET /users/:id/edit edit Return a form for editing the user. /resource/users.xqy?action=edit&id=:id

An sample request:

 Request       : PUT /users/1
 routes.xml    : <routes> 
                   <resources name="users" webservice="true"/> 
                 </routes>
 Dispatches to : /resource/users.xqy?action=put&id=1

Member Includes

Sometimes you will need to include one or more actions that are not part of the default resource, e.g. you might want to create a enable or disable one of your users.

For this you need the resource to respond to PUT /users/dscape/enabled and understand that should re-enable the user. This action runs against a specific user - that's why we call it member include. Here's an example of how you can express that in rewrite:

 Request       : PUT /users/dscape/enabled
 routes.xml    : <routes> 
                   <resources name="users">
                     <member action="enabled" for="PUT,DELETE"/>
                   </resources>
                 </routes>
 Dispatches to : /resource/users.xqy?action=enabled&id=dscape

If you are curious about the DELETE - it's simply there to allow you to disable a user the RESTful way. If you don't pass the for attribute then GET will be the default.

Set Includes

Another type of action you might need to add are global actions, e.g. searching all users in full text.

We call this a set include and express it as follows:

 Request       : PUT /users/search?q=foo
 routes.xml    : <routes> 
                   <resources name="users">
                     <member action="enabled" for="PUT,DELETE"/>
                     <set action="search"/>
                   </resources>
                 </routes>
 Dispatches to : /resource/users.xqy?action=search&q=foo

Member and set includes are not exclusive of each other and you can use as many as you want in your resources.

Something went wrong with that request. Please try again.