Introduction

Overview

uREST is implemented as set of vanilla JSON over HTTP web services using all four verbs (GET/POST/PUT/DELETE). Every resource has it's own URL and is manipulated in isolation. In other words, uREST tries to follow the REST principles as much as possible. uREST is built on top of the Open Source OpenRasta framework.

Authentication

Authentication is managed using custom QueryString based authentication. Every request must include a set of auth_username and auth_token key value pairs. Where auth_username is your Umbraco username, and auth_token is your uREST authentication token. See the documentation on the Token resource for details on how to obtain a uREST authentication token.

GET http://www.yoursite.com/rest/{resource}?auth_username=admin&auth_token=76c1787eeeaad3a728fe0e9149713374f20430e5

Making Requests

Be sure to set both the 'Accept' and 'Content-Type' headers to 'application/json' to identify the request and response format.

GET http://www.yoursite.com/rest/{resource}?auth_username={usrname}&auth_token={token}
Accept: application/json
Content-Type: application/json
As with all REST web services, the HTTP method used when making the request defines the type of action to perform on a resource:

Method Action
GET Retreives a resource
POST Creates a resource
PUT Updates a resource
DELETE Deletes a resource

If you are using a HTTP client unable to make PUT or DELETE requests, you can instead make a POST request and set the 'X-HTTP-Method-Override' header to the actual method you wish to perform. uREST will then automatically route the request to the relevant method.

Example: To update a resource using the 'X-HTTP-Method-Override'

POST http://www.yoursite.com/rest/{resource}/{id}?auth_username={username}&auth_token={token}
X-HTTP-Method-Override: PUT

Responses

If a request succeeds, it will return a status code in the 200 range and often, an JSON-formatted response. Note that, in general, if a request causes a record to be created or updated, the response will use the '201 Created' status, if a request causes a record to be removed, the response will use the '204 No Content' status, any other successful operation will return a '200 OK' status code. If a request fails, a non-200 status code will be returned.

If you are using a HTTP client unable to handle HTTP status codes (such as Flash), you can force uREST to legacy mode, by setting the 'X-HTTP-Protocol-Support' header to 'legacy'. When set, all uREST requests will return a '200 OK' status code along with an additional response header 'X-HTTP-Status-Code' containing the original status code.

Last edited Dec 19, 2010 at 6:40 PM by mattbrailsford, version 15

Comments

No comments yet.