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/Overview"

(REST URI Design Principles)
(REST URI Design Principles)
Line 26: Line 26:
  
 
==== REST URI Design Principles ====
 
==== REST URI Design Principles ====
A URI is structured as follows: domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]
+
A URI (domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]) should be structured as follows:
  
 
# 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.
 
# 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.

Revision as of 15:20, 17 October 2011

Database RESTful Service ()DBRS Overview

DBRS provides platform-neutral, JAX-RS compliant access to relational database artifacts via RESTful web services1. DBRS leverages EclipseLink's existing JPA and JAXB components as well as the Jersey JAX-RS v1.1 reference implementation.

DBRS at its core is primarily a design-time utility - an application generator - that with a minimum amount of pre-existing configuration plus a database to 'scrape' for meta-data, generates a simple CRUD-style application.


Database RESTful Service ()DBRS Overview

DBRS provides platform-neutral, JAX-RS compliant access to relational database artifacts via RESTful web services1. DBRS leverages EclipseLink's existing JPA and JAXB components as well as the Jersey JAX-RS v1.1 reference implementation.

DBRS at its core is primarily a design-time utility - an application generator - that with a minimum amount of pre-existing configuration plus a database to 'scrape' for meta-data, generates a simple CRUD-style application.


1 RESTful web services (from Wikipedia)

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 architect 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 DELETE; optional operations TRACE, OPTIONS, etc. rarely used (analogous to the database semantics of CRUD: Create, Retrieve, Update and Delete).
  4. use of hyperlinks and URIs to interact with and navigate to resources.

REST URI Design Principles

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

  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. a URI should be succinct and easy-to-understand: '/some/resource/about' is preferred over '/some/resource/about-acme-corp'.
  3. the URI structure should be consistent: once the strategy is chosen, follow it. As in i), 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
   vi) 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.
  vii) 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, not 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.
  viii) 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://.../myproject/entities/employees - returns a list of employees
           GET http://.../myproject/entities/employees/count - returns a count of the list of employees
           GET http://.../myproject/entities/employee/1 - returns the employee identified in the database with primary key 1
  ix) 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://.../myproject/entities/employees/?pgNum=0&pgSize=40 - returns the first group of 40 employees
           GET http://.../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.

Back to the top