|
|
| (22 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| + | ignore |
| − | == Database RESTful Service ()DBRS Overview ==
| + | |
| − | <onlyinclude>
| + | |
| − | DBRS provides platform-neutral, JAX-RS compliant access to relational database artifacts via RESTful web services<sup>1</sup>. 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 <i>application generator</i> - that with a minimum amount of pre-existing configuration plus a database to 'scrape' for meta-data, generates a simple CRUD-style application.
| + | |
| − | | + | |
| − | </onlyinclude>
| + | |
| − | | + | |
| − | ====<sup>1</sup> RESTful web services (from Wikipedia) ====
| + | |
| − | The term REST - <b>RE</b>presentational <b>S</b>tate <b>T</b>ransfer - was introduced and defined in 2000 by [http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm Roy Fielding in his doctoral dissertation] (Fielding is one of the principal authors of the HTTP v1.1 spec). Conforming to the REST constraints is referred to as being <b>RESTful</b>
| + | |
| − | | + | |
| − | A RESTful web service (also called a RESTful [http://en.wikipedia.org/wiki/Web_API web API]) is a simple web service implemented using HTTP and the principles of REST. It is a collection of resources, with four defined aspects:
| + | |
| − | # use of URIs for all resources exposed by the web service: e.g. <nowiki>http://example.com/resources/<b><i>car</i></b></nowiki>
| + | |
| − | # use of Internet media types for on-the-wire representation. This is often JSON or XML, but can be any valid Internet media type.
| + | |
| − | # use of the supported HTTP v1.1 operations: POST, GET, PUT, and DELETE ([http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete typically mapped to the database semantics of CRUD: <b>C</b>reate, <b>R</b>etrieve, <b>U</b>pdate and <b>D</b>elete])
| + | |
| − | # use of hyperlinks and URIs to interact with and navigate to resources.
| + | |
| − | | + | |
| − | General URI structure:
| + | |
| − | domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]
| + | |
| − | | + | |
| − | Review of REST-ful URI design principles:
| + | |
| − | | + | |
| − | i) 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.
| + | |
| − | ii) a URI should be succinct and easy-to-understand: '/some/resource/about' is preferred over '/some/resource/about-acme-corp'.
| + | |
| − | iii) 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.
| + | |
| − | iv) 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
| + | |
| − | v) 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.
| + | |
