EclipseLink/Development/DBWS/RestfulComponent/Design

DBRS Design

The DBRS utility generates RESTful applications (see below for more details on RESTful design principles). Of primary importance is the design of the URIs for each resource (a.k.a. entity):

URI	Operation	Result
/myproject/entities/employees/	GET PUT POST DELETE	retrieve list of employees (200 OK) replace list of employees (201 Created) add a new employee (201 Created) unused (400 Bad Request)
/myproject/entities/employees/count	GET (with search modifier)	retrieve a count of the list of employees (200 OK)
/myproject/entities/employees/?pgNum=0&pgSize=40	GET (with query parameters)	retrieve the first group of 40 employees (200 OK) Message body should include the following additional information: pageNum: reflects the pgNum query parameter pageSize: reflects the pgSz query parameter (or the default page size) itemsInPage: reflects the total number of items in the current page totalItems: reflects the total number of items found for the list
/myproject/entities/employee/{id}	GET PUT POST DELETE	retrieve employee details (200 OK | 404 Not Found) update employee details (201 Created | 404 Not Found). If the message body is missing an employee attributes, sparse update logic used add a new employee (201 Created) remove employee (204 No Content | 404 Not Found)

In addition, the URIs for an entity's meta-resources: the in-memory representation of the ORM and OXM meta-data as specified by the JPA2 spec:

RESTful URI Design Principles

The term REST - REpresentational State Transfer - was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation (Fielding is one of the principal authors of the HTTP v1.1 spec). Conforming to Fielding's architecture is referred to as being RESTful. A RESTful web service (also called a RESTful web API) is implemented using HTTP and the principles of REST, with emphasis on the following aspects:

1. definition of URIs for all resources exposed by the web service: e.g. /myproject/entities/car
2. use of Internet media types for on-the-wire representation. This is often JSON or XML, but can be any valid Internet media type.
3. use of the HTTP v1.1 operations: POST, GET, PUT, and DELETE - analogous to the database semantics of CRUD: Create, Retrieve, Update and Delete.
4. use of hyperlinks to interact with/navigate to resources.

A URI is structured as follows: domainname/[contextual key(s)]/[resource name]/?[query args and modifiers] and should follow the following Design Principles:

1. A URI must represent a unique object, permanently: if it becomes necessary to relocate a resource, use the response code HTTP 301 (redirect) so that the client can find where the resource has been moved to.
2. should be succinct and easy-to-understand: /some/resource/about is preferred over /some/resource/about-acme-corp.
3. A URI's structure must be consistent: once the strategy is chosen, follow it. As in 1), if the strategy changes, return HTTP 301 so that users familiar with resources under the previous structure can find them under the new structure.
4. A URI must follow POLA - Principle Of Least Astonishment: URIs should be structured so that they are intelligibly 'hackable'. For example, if the URI /events/2010/01 represents the events for January 2010, then it follows that:

   /events/2009/01 - represents events for January 2009

   /events/2010 - represents events for the entire year of 2010

   /events/2010/01/21 - represents events for January 21st, 2010

5. URIs should be composed of keywords that are important to the context of the resource. Typical contextual keys describe:

   a resource's type

   a resource's category - or parent category

   key resource data/attributes (i.e. the date posted)

   
   

   Typically, a URI specifies a categorization that moves from general to specific, e.g. a descending hierarchy like year -> month -> day

6. A URI should not contain any markers that would allow someone to infer (correctly or otherwise!) what sort of underlying implementation technology is being used. Suffixes such as .php or .aspx should not be used.
7. A URI should be lowercase up to the [resource name] - query args and modifiers can be mixed case. In addition, query args and modifiers change only the view presented for a resource, never its underlying representation. For example a chart service may show some rows from a database; a query modifier may indicate that the chart should be rendered as a PDF file instead of a PNG image - the presence of the query modifier should in no way alter the information contained in the rows.
8. A URI that refers to a list of resources should use plural nouns; a URI that refers to a single resource should use singular nouns:

   GET /myproject/entities/employees - returns a list of employees

   GET /myproject/entities/employee/1 - returns the first employee

9. Pagination of returned lists of resources is supposed to be managed via HTTP header attributes called HTTP Ranges. Unfortunately, this requires returning response code HTTP 206 (Partial Content) which is not universally accepted by clients. Thus pagination is typically accomplished by appending query modifiers to indicate page number and size:

   GET http://example.com/myproject/entities/employees/?pgNum=0&pgSize=40 - returns the first group of 40 employees

   GET http://example.com/myproject/entities/employees/?pgNum=1&pgSize=20 - returns the next group of 20 employees

To protect the server from 'greedy' clients that try to query the entire database, use the response code HTTP 413 (Request Entity Too Large) if necessary. The Entity tag (ETag) header, when used with Last-Modified/If-None-Modified/If-Modified-Since headers, is essential for handling the lost update problem when editing resources selected from (partial) paginated lists.