|
|
| (77 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__== DBRS Design == The DBRS utility generates '''RESTful''' applications (see [[#RESTful_URI_Design_Principles|below]] for more details). Of primary importance is the design of the URIs for each resource (a.k.a. entity):<br>
| + | ignore |
| − | | + | |
| − | {| cellspacing="1" cellpadding="1" border="1" style="width: 358px; height: 114px;"
| + | |
| − | |+ Generated Resource URIs
| + | |
| − | |-
| + | |
| − | | URI<br>
| + | |
| − | | Operation<br>
| + | |
| − | | Result<br>
| + | |
| − | |-
| + | |
| − | | http://.../myproject/entities/employees/<br>
| + | |
| − | | GET<br>
| + | |
| − | | list of all employees (200 OK)<br>
| + | |
| − | |-
| + | |
| − | | <br>
| + | |
| − | | <br>
| + | |
| − | | <br>
| + | |
| − | |}
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | 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:
| + | |
| − | | + | |
| − | [[Image:JPA2Metamodel.png]]
| + | |
| − | | + | |
| − | ===== RESTful URI Design Principles =====
| + | |
| − | | + | |
| − | The term REST - '''RE'''presentational '''S'''tate '''T'''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 Fielding's architecture is referred to as being '''''RESTful'''''. A RESTful web service (also called a RESTful [http://en.wikipedia.org/wiki/Web_API web API]) is implemented using HTTP and the principles of REST, with emphasis on the following aspects:
| + | |
| − | | + | |
| − | #definition of URIs for '''all''' resources exposed by the web service: e.g. <nowiki>http://example.com/resources/</nowiki>'''''car'''''
| + | |
| − | #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 HTTP v1.1 operations: POST, GET, PUT, and DELETE - [http://en.wikipedia.org/wiki/Create%2C_read%2C_update_and_delete analogous to the database semantics of CRUD: '''C'''reate, '''R'''etrieve, '''U'''pdate and '''D'''elete].
| + | |
| − | #use of hyperlinks to interact with/navigate to resources.
| + | |
| − | | + | |
| − | A URI is structured as follows: <tt>domainname/[contextual key(s)]/[resource name]/?[query args and modifiers]</tt> and should follow the following Design Principles:
| + | |
| − | | + | |
| − | #A URI 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.
| + | |
| − | #should be succinct and easy-to-understand: <tt>/some/resource/about</tt> is preferred over <tt>/some/resource/about-acme-corp</tt>.
| + | |
| − | #A URI's structure must be consistent: once the strategy is chosen, follow it. As in 1), if the strategy changes, return <tt>HTTP 301</tt> so that users familiar with resources under the previous structure can find them under the new structure.
| + | |
| − | #A URI must follow '''POLA''' - [http://http://en.wikipedia.org/wiki/Principle_of_least_astonishment| '''P'''rinciple '''O'''f '''L'''east '''A'''stonishment]: URIs should be structured so that they are intelligibly 'hackable'. For example, if the URI <tt>/events/2010/01</tt> represents the events for January 2010, then it follows that:
| + | |
| − | #:<tt>/events/2009/01</tt> - represents events for January 2009
| + | |
| − | #:<tt>/events/2010</tt> - represents events for the entire year of 2010
| + | |
| − | #:<tt>/events/2010/01/21</tt> - represents events for January 21st, 2010
| + | |
| − | #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)<div style="line-height:125%"><br></div>Typically, a URI specifies a categorization that moves from general to specific, e.g. a descending hierarchy like year -> month -> day
| + | |
| − | #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 <tt>.php</tt> or <tt>.aspx</tt> should not be used.
| + | |
| − | #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.
| + | |
| − | #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 <tt><nowiki>http://example.com/myproject/entities/employees</nowiki></tt> - returns a list of employees
| + | |
| − | #::GET <tt><nowiki>http://example.com/myproject/entities/employees/count</nowiki></tt> - returns a count of the list of employees
| + | |
| − | #::GET <tt><nowiki>http://example.com/myproject/entities/employee/1</nowiki></tt> - returns the first employee
| + | |
| − | #Pagination of returned lists of resources is supposed to be managed via HTTP header attributes called HTTP Ranges. Unfortunately, this requires returning response code <tt>HTTP 206 (Partial Content)</tt> which is not universally accepted by clients. Thus pagination is typically accomplished by appending query modifiers to indicate page number and size:
| + | |
| − | #::GET <tt><nowiki>http://example.com/myproject/entities/employees/?pgNum=0&pgSize=40</nowiki></tt> - returns the first group of 40 employees
| + | |
| − | #::GET <tt><nowiki>http://example.com/myproject/entities/employees/?pgNum=1&pgSize=20</nowiki></tt> - 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 <tt>HTTP 413 (Request Entity Too Large)</tt> if necessary. The Entity tag (ETag) header, when used with <tt>Last-Modified/If-None-Modified/If-Modified-Since</tt> headers, is essential for handling the ''[http://www.w3.org/1999/04/Editing lost update problem]'' when editing resources selected from (partial) paginated lists.
| + | |
