Implementing a RESTful Service Server-Side

Authors:Kitson Kelly

You find yourself banging your head against the wall, because you hear all the “cool kids” are using REST and you see there is quite an extensive implementation of RESTful clients in dojo, and your boss says “I want some of that”. Well, hopefully this tutorial can help you out.

First you have to accept what REST is and isn’t. Then you have to understand how Dojo uses REST and then finally you can consider what you need to do to implement REST on the server side. While this tutorial will try to be generic, my current service side language of choice is PHP, so most of my server side explanations will likely be in the context of PHP.

Basics of RESTful Services

A lot of people stumble across RESTful services and expect to find a well fleshed out standard with some hard and fast rules. That is the first thing you have to get over when it comes to REST. REST is a convention or pattern. It is basically leveraging the HTTP protocol and methodology to provide hierarchical data services. The fates of the provider and consumer are inexplicably linked.

Personal commentary, is that standards like SOAP and XML-RPC and XML, which have driven technology for the past decade, have given us this false sense that any provider can talk to any other consumer without knowing an iota about each other. This is simply silly. Very few people implement a provider or consumer without some level of conversation or dialogue. The technology community has heaped and layer upon layer of structure to protect providers from consumers and in my opinion, REST gets back to basics of implementing basic CRUD functions in a simple and logical way.

The side affect of this simplicity, is that the provider and consumer need to know each other very well and they need to trust each other to a certain degree. But this really was the way it was before, but other standards just pretended to save us from that, but were never fully realised.

What is a RESTful Service?

REST stands for Representational State Transfer. It basically leverages the HTTP protocol and model to provide data services. What REST should be is follow a client/server model, be stateless, cacheable, allow for a layered model and provide a uniform interface.

All resources are identified by the use of a URI, and there are two types of URIs used, collection URIs and element URIs. For example, let’s assume we have a server that is providing data about users. The following URI would refer to the users:

Now if we wanted to refer to just a specific user, we would add the specific resource identifier to the URI. For example:

This would refer to the user who has an identity of 1.

Building on the resource identification, all the Create, Read, Update and Delete (CRUD) functions are available via the use of the HTTP protocol verbs. The main ones being GET, POST, PUT and DELETE. Different parts of a collection can be specified by adding another collection identifier after an element identifier in the URI. Also, a provider could provide access to data in different ways in a fashion that is most logical. For example, users might have a set of groups they belong to. A provider could provide the groups the user belongs to by using the following URI:

And provide all the possible groups via the URI:

And even provide all the users that are part of a specific group:

REST provides a fair amount of flexibility up to the provider to determine what and how they provide.

One important thing to note is that REST is independent from the data that transports it. It is expected that the server and the client will negotiate on how the data is represented. The most common (especially in Dojo) way to return data is JSON, although XML, Text or any other data format could easily be used. It will just be assumed here that JSON will be used without further explanation.

HTTP Verbs

The HTTP protocol verbs in REST allow for traditional CRUD functions to happen. Each of the verbs and how they are used are detailed below.


The HTTP verb GET is used to list or retrieve resources. For collections, the service should return an array of items that are members of the collection. These can be the full details, or just information on where to find the additional data about each resource. So the following:


Would retrieve something like:

      {"id": 1, "userName": "jsmith", "firstName": "John", "lastName": "Smith"},
      {"id": 2, "userName": "jdoe", "firstName": "Jane", "lastName": "Doe"},
      {"id": 3, "userName": "bill", "firstName": "Bill", "lastName": "Keese"}

While requesting a specific resource like:


Would return just the object:

{"id": 1, "userName": "jsmith", "firstName": "John", "lastName": "Smith"}


The HTTP verb POST is used to create new resources. Again, REST does not specify how the data is sent, it could be traditional form encoded data, but both the Dojo implementations of REST will POST new records, and expect the server to provide the appropriate location URI for the new resource. The server should respond with a Location: response header like:



The HTTP verb PUT is used to “replace” the content of an existing object with the provided content. If a collection URI is specified, the entire data set should be replaced with the provided one, where as an element URI would replace that specific element.


The HTTP verb DELETE is used to delete resources. If a collection URI is specified, the whole collection should be deleted. If an element URI is specified, just that specific item should be deleted.


While not currently implemented in either of the JSON REST consumers in Dojo, some RESTful implementations use the HTTP verb OPTIONS to provide information about what verbs can be supplied for a specific URI. This would allow a consumer to determine if a resource could be added, updated or deleted.

Dojo and REST

The Dojo RESTful consumers are fairly straight forward when it comes to REST, and there is essentially feature parity between both the and the As Dojo moves away from the DataStore API to the new Store API, developers can expect that will become the main focus of RESTful implementation in Dojo. Currently though, most data aware widgets only consume the DataStore API, although “wrapping” the with the is possible.

Introduced in Dojo 1.6, the is a good an efficient implementation of a RESTful consumer. To make it have feature parity with the, the developer should wrap the store in and

The defaults to assuming the identifier property of each element is id, therefore if your provider returns an elements identifier in that field, most developers simply need to specify the target URI for the collection.

An example of programmatically creating a full featured store would be:

var userMemoryStore = new;
var userJsonRestStore = new{target: "/users/"});
var userStore = new, userMemoryStore);

More details can be found in their respective Dojo documentation pages.

Introduced in Dojo 1.2, the has been the “workhorse” of Dojo DataStores. It provides the Read, Identity, Write and Notification APIs.

An example programmatic declaration would be:

var userDataStore = new{
  target: "/users/",
  idAttribute: "id"

An example of declarative would be:

<div data-dojo-type="" data-dojo-id="userDataStore"
    data-dojo-params="target: '/users/', idAttribute: 'id'"></div>

Note it is necessary to use data-dojo-id with non-Widget (dijit) declarative objects, like DataStores in order to make available a JavaScript variable that can be passed to other declarative objects. Also it should be noted that these objects do not get destroyed if their containing widget is destroyed and the variable is declared in a global scope.

RESTful Conventions the Dojo Way

Both the and provide some enhancements to the basic RESTful functionality.



Widgets can specify sorting and those are passed as part of the query string of the URI on the GET. The sort is specified by the sort attribute in either the store.get() or datastore.fetch() function. This gets converted into a query attribute named sort with a comma separated list of attributes with a + or - indicating if the attributes should be sorted ascending or descending. For example, the following sort value:

{sort: [
  {attribute: "id"},
  {attribute: "userName", descending: true}

Would translate into the following:



Widgets can (and do) specify a start and count attributes when accessing data. These get translated by the Store or DataStore specifying the Range HTTP header.

For example, the following:

  start: 5,
  count: 10

Would result in the following HTTP request header being sent:

Range: items=5-15

Any server should respond by setting the Content-Range header with the value of the range of items being returned and a total counts of all of the items that could be returned based on the query. Because the total possible items is returned, the downstream widgets will “know” there are more items which they can retrieve. Also the provider should respond with the amount of items they are returning, even if more items are being requested.

So, if a request was for a count of 10 items starting at 5, but there are only 10 items in total, the following HTTP response header should be set:

Content-Range: items 5-9/10

Note start is 0 based, so starting at 5 means the 6th item.

JSON the Dojo Way

While JSON is a great way of describing arbitrary objects, it doesn’t have a standard for referencing. The good news is that Dojo solves that via dojox.json.ref which provides everything you need. It is also generally used by the rest of the framework, including the JSON REST datastores and stores. This gives you quite a bit of flexibility in how you provide data.

Mainly, it focuses on the attribute name $ref which provides a “pointer” to the rest of the data. In a REST services, this is a URI. When a client requests the data from the store, and the store doesn’t have it, it will attempt to fetch the data at the supplied URI. The typical way this is used is on collection URIs to provide references to the full resource, when you only want to provide a portion of the data up front. For example, let’s assume you want to provide information about pages of a book and you have the following collection URI:


Which returns an array that provides some basic information, but not the content of the page, but a reference to the item:

  {"id": "page/1", "chapter": "1", "$ref": "page/1"},
  {"id": "page/2", "chapter": "1", "$ref": "page/2"},
  {"id": "page/3", "chapter": "1", "$ref": "page/3"}

And then something tries to attempt to access an attribute of a page that isn’t loaded (like text) the store will attempt to do the following:


Which could result in you returning the whole object, that would have been inefficient until the consumer needed the data:

  "id": "1",
  "chapter": "1",
  "text": "..."

The other main way to use $ref in a REST environment is to specify children. Again, speaking about a book, we could provide a reference back when a request is made to a collection or resource URI:


Would return something like:

  "id": "1",
  "title": "My Little Book of Dojo",
  "author": "Kitson Kelly",
  "children": {"$ref":"1/page"}

There is a lot more you can do with referencing, but viewing the dojox.json.ref page is the best way to get a complete picture. Just remember that your references should contain a relative URI to the appropriate information.

Server-Side Implementation

As stated before, a lot of the structure of a provider’s data is based on its application and how it will be consumed. Some Widgets have specific expectations of how data is structured than can drive the need of how it is provided. There are however some general concepts of how a JSON REST store expects things to be handled and some general good practices.

General Structure

However you implement your RESTful service, you need to provide some basic functionality:

  • Handle HTTP requests
  • Provide HTTP responses
  • Encode return data in JSON
  • Decode POSTed and PUTed data from JSON
  • Handle ranges, sorting and querying/filtering as almost every Widget expects one or all of these to be supported

Other things you might want to consider:

  • Support compression, since you are returning data and most browsers support it, you can save a lot of bandwidth by supporting it.
  • Support other content types other than JSON, so that other data can be retrieved from your RESTful service.
  • Provide method invocation to perform a server side service.
  • Error handling and logging

HTTP Response Codes

HTTP Headers Received

HTTP Headers Sent

Error in the documentation? Can’t find what you are looking for? Let us know!