Difference between revisions of "PhyloWS/REST"

From Evolutionary Informatics Working Group
Jump to: navigation, search
m (Principles)
(Principles)
Line 8: Line 8:
 
# The architecture builds on the principle of viewing data and operations as resources, which get created, modified (delete, update), or retrieved.  
 
# The architecture builds on the principle of viewing data and operations as resources, which get created, modified (delete, update), or retrieved.  
 
# The allowable HTTP method (GET, POST, PUT, DELETE) depends on the type of [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete CRUD] operation being represented by the resource call. For example, resource calls that simply retrieve data without also creating a resource should use the GET method, and not POST. <br/>Note that a resource may be created virtually; for example, calling a resource might start a calculation and return the results directly (rather than returning a URL to the results, which would be more appropriate). Nonetheless, the calculation is still being created. ''Question: is the mapping PUT=create, GET=retrieve, POST=update, DELETE=delete? If so, what is PUT used for? Is a message body being submitted? I don't think so...''
 
# The allowable HTTP method (GET, POST, PUT, DELETE) depends on the type of [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete CRUD] operation being represented by the resource call. For example, resource calls that simply retrieve data without also creating a resource should use the GET method, and not POST. <br/>Note that a resource may be created virtually; for example, calling a resource might start a calculation and return the results directly (rather than returning a URL to the results, which would be more appropriate). Nonetheless, the calculation is still being created. ''Question: is the mapping PUT=create, GET=retrieve, POST=update, DELETE=delete? If so, what is PUT used for? Is a message body being submitted? I don't think so...''
# The API should also be described as a WSDL document. In fact, WSDL 2.0 allows binding to HTTP methods and supports a RESTful interface.
+
# The API should also be described as a WSDL document. In fact, [http://www.w3.org/TR/wsdl20/ WSDL 2.0] allows binding to HTTP methods and supports a RESTful interface.
 +
#* See the [http://en.wikipedia.org/wiki/Web_Services_Description_Language#Example_WSDL_file example in the Wikipedia entry], the [http://www.w3.org/TR/wsdl20-primer/ W3C's WSDL 2.0 Primer] (specifically the [http://www.w3.org/TR/wsdl20-primer/#more-bindings-http section on HTTP binding]), and the [http://www.w3.org/TR/wsdl20-adjuncts/ Adjuncts part of the WSDL 2.0 spec] (and again, specifically the [http://www.w3.org/TR/wsdl20-adjuncts/#http-binding section on HTTP binding]).
 +
#* According to the WSDL 2.0 [http://www.w3.org/TR/wsdl20-adjuncts/#http-binding HTTP-binding extension], input messages (defined as XML structure) can be mapped to parts of the query path as well as query parameters (and a combination of both).
 +
#* In addition, the PhyloWS WSDL document can also define a SOAP binding.
  
 
==Basic structure==
 
==Basic structure==

Revision as of 04:53, 14 February 2008

Specification for a REST-based instantiation of the PhyloWS API.

Disclaimer: Note that this is pre-alpha, work in progress, and not even nearly finished. Any comments highly appreciated.

Principles

  1. RESTful queries should be stateless, hence all needed input needs to be provided in a single call, rather than "accumulating" the input (if there are multiple pieces of input) over multiple calls.
  2. The architecture builds on the principle of viewing data and operations as resources, which get created, modified (delete, update), or retrieved.
  3. The allowable HTTP method (GET, POST, PUT, DELETE) depends on the type of CRUD operation being represented by the resource call. For example, resource calls that simply retrieve data without also creating a resource should use the GET method, and not POST.
    Note that a resource may be created virtually; for example, calling a resource might start a calculation and return the results directly (rather than returning a URL to the results, which would be more appropriate). Nonetheless, the calculation is still being created. Question: is the mapping PUT=create, GET=retrieve, POST=update, DELETE=delete? If so, what is PUT used for? Is a message body being submitted? I don't think so...
  4. The API should also be described as a WSDL document. In fact, WSDL 2.0 allows binding to HTTP methods and supports a RESTful interface.

Basic structure

  1. All resource URIs start with BASE_URL/phylows/. BASE_URL is specific to the implementing service.
  2. Optional resources may not be implemented.
  3. The first path element designates the type of data the resource points to, or the operation.
    • Examples for data: /phylows/tree, /phylows/clade, /phylows/node
    • Examples for operation: /phylows/aggregate, /phylows/find
  4. The second path element depends on whether the resource points to a data resource or to an operation:
    • Data resources: The second path element gives the unique identifier of the data resource. This need not (and arguably should not) be the primary key of the resource in the provider database, but could also be an accession number-type identifier.
    • Operation resources: The second path element gives the data type being acted on, or being returned. Subsequent path elements specify the query path, with final parameters giving query parameters.
      • Examples: /phylows/find/tree, with additional parameters specifying the query, e.g.: /phylows/find/tree/?name=Primates