Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/DBWS/RestfulComponent/Design"

(RESTful URI Design Principles)
Line 9: Line 9:
  
 
==== RESTful URI Design Principles ====
 
==== RESTful URI Design Principles ====
A URI (domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]) should be structured as follows:
+
URI: <tt>domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]</tt> should be structured as follows:
  
 
# must represent a unique object, permanently: if it becomes necessary to relocate a resource, use the response code <tt>HTTP 301 (redirect)</tt> so that the client can find where the resource has been moved to.
 
# must represent a unique object, permanently: if it becomes necessary to relocate a resource, use the response code <tt>HTTP 301 (redirect)</tt> so that the client can find where the resource has been moved to.

Revision as of 16:23, 17 October 2011

DBRS Design

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. http://example.com/resources/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 DELETE1 - analogous to the database semantics of CRUD: Create, Retrieve, Update and Delete.
  4. use of hyperlinks to interact-with and navigate-to resources.

1 optional operations such as TRACE, OPTIONS, etc. rarely used .

RESTful URI Design Principles

URI: domainname/[contextual key(s)]/[resource name]/?[query args and modifiers] should be structured as follows:

  1. 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. the structure should 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. principle-of-least-surprise: URIs should be structured so that they are intelligibly 'hackable' - e.g. if /events/2010/01 shows a monthly calendar with events from January 2010, then it follows that:
    /events/2009/01 - should show an events calendar for January 2009
    /events/2010 - should show events for the entire year of 2010
    /events/2010/01/21 - should show the 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 (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. 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 http://example.com/myproject/entities/employees - returns a list of employees
    GET http://example.com/myproject/entities/employees/count - returns a count of the list of employees
    GET http://example.com/myproject/entities/employee/1 - returns the employee identified in the database with primary key 1
  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 very useful in handling the Lost Edit problem when editing resources selected from partial paginated lists.

The DBRS utility builds an in-memory representation of the required meta-data for the employee entity to be mapped to the database via a JPA entity and mapped to any RESTful clients via JAXB (supporting both XML and JSON media representations). Initially the back-end generation will target EclipseLink JPA/JAXB + Jersey (1.9.1 at the time of this writing).

Back to the top