Simulation Data Access Protocol (SimDAP) DraftThis page is for outlining the initial draft of the SimDAP Note. Once we've reached agreement on the outline, we will move content to an HTML version in the volute repository. | ||||||||
Changed: | ||||||||
< < | Please hold of on editing this, I'm still transferring some of my notes. I should be done later today. | |||||||
> > | The current outline is in, I'll try to flesh it out some over the weekend. | |||||||
Changed: | ||||||||
< < | -- RickWagner - 11 Nov 2008 | |||||||
> > | -- RickWagner - 14 Nov 2008 | |||||||
1. Introduction2. SimDAP Data Model3. Interface Overview3.1 ArchitectureA SimDAP service provides access to initial or derived files from simulations.3.2 Service OperationsA SimDAP service implements multiple service operations, each of which performs some well defined function when invoked by a client application. The service operations described here use HTTP GET and POST as the low level communications protocol. The functionality of each operation is defined independently of the low level communications protocol, and semantically equivalent operations could be implemented in the future via other protocols. SimDAP defines the following standard service operations:
3.3 Service ProfileThe basic form of a SimDAP service is specified in detail in section ??. In the current section we merely summarize the elements of the basic service interface.3.3.1 Request FormatA service may implement multiple service operations, such as download or preview; these define the service interface. Interfaces may change with time and hence are versioned. It is possible for a given service instance to simultaneously expose multiple interfaces or versions of interfaces. The SimDAP interface described in this document is based upon a distributed computing platform (DCP) comprising Internet hosts that support the Hypertext Transfer Protocol (HTTP). Thus, the online representation of each operation supported by a service is composed as a HTTP Uniform Resource Locator (URL). A request URL is formed by concatenating a baseURL with zero or more operation-defined request parameters. The baseURL defines the network address to which request messages are to be sent for a particular operation of a particular service instance on a particular server. Service operations generally share the same baseURL but this is not required. | ||||||||
Added: | ||||||||
> > | Example:
$/sync?REQUEST=download&EXPERIMENT=...SimDAP defines two versions of the baseURL, one for synchronous operations and another for asynchronous operations. These are formed by contentating the service-baseURL with either /sync? or /async?. Hence for synchronous operations we have a full baseURL of /sync?and for asynchronous operations the full baseURL is /async?In general the service operation is much the same whether or not it executes synchronously or asynchronously. Minor differences in service operation function or input parameters are poindividual service operation below. Note that since a URI pathname segment is appended to the service baseURL the service baseURL may not contain any HTTP GET parameters, and must be a fixed URI. 3.3.2 ParametersParameters may appear in any order. If the same parameter appears multiple times in a request the operation is undefined (if alternate values for a parameter are desired the range-list syntax may be used instead). Parameter names are case-insensitive. Parameter values are case-sensitive unless defined otherwise in the description of an individual parameter. All service operations define the following standard parameters, which are part of the basic service profile:
3.3.3 Parameter ValuesInteger numbers are represented as defined in the specification of integers in XML Schema Datatypes. Real numbers are represented as specified for double precision numbers in XML Schema Datatypes. Sexagesimal formatting is not permitted, either for parameter input or in formal output metadata, other than in ISO 8601 formatted time strings (sexagesimal format is permitted in any informal output intended for a human, e.g., text or HTML formatted tables). SimDAP defines a special range-list format for specifying numerical ranges or lists of ranges as parameter values. For example, 1E-7/3E-6 specifies a closed range from 1E-7 to 3E-6 inclusive. The syntax supports both open and closed ranges. Ranges or range lists are permitted only when explicitly indicated in the definition of an individual parameter. A variant of the range list is the value of the WHERE parameter, used to specify the query constraint for a ParamQuery operation. For a full description of range list syntax refer to section 3.3.1.3.3.4 Use of GET and POSTWhere specified, individual service operations may provide both HTTP GET and POST forms for issuing the service request. Both forms share the same input parameters and operation semantics, being merely two different ways of invoking the same service operation. In general, the GET form is used for synchronous operations which are idempotent (have no side effects, the result is cacheable, multiple instances may be simultaneously active and will return the same result). POST is used for any request which has a side effect, e.g., initiation of an asynchronous job, or which needs to pass a large amount of data to the service, e.g., uploading a table or region mask to be used within a query.3.3.5 URL EncodingURL encoding (see section 7.3.2) is a standard technique used to encode characters appearing in HTTP requests, such as a GET URL, to pass characters which are not otherwise legal and could interfere with the HTTP protocol. By using URL encoding it is possible to pass arbitrary character data to a service in a HTTP request, for example an arbitrary ADQL statement could be passed in a simple GET request so long as it is not too large for a GET URL (2K or so characters).3.3.6 Error ResponseIn the case of an error, service operations should return a VOTable containing an INFO element with name QUERY_STATUS and the value set to ERROR. More fundamental service or protocol errors may result in an HTTP level protocol error, hence a client program should be prepared to handle either response. A null query, that is a queryData which does not find any data, is not considered an error; likewise an overflow condition is distinguised from error. More information on error responses is given in section 7. | |||||||
3.4 Request Examples | ||||||||
Added: | ||||||||
> > | Some examples of simple SimDAP requests follow. These are intended only to help introduce and illustrate basic usage of the SimDAP service interface; the details are specified in the following sections of this document.
Synchronous parametric query performing a simple cone search of table (baseURL would be replaced with the actual service base URL):
$baseURL/sync?REQUEST=paramquery&POS=12,34&SIZE=0.5&FROM=fooSynchronous ADQL query returning all data from table: $baseURL/sync?REQUEST=adqlquery&QUERY=select+*+FROM+fooSimple cone search query executed asynchronously: curl -d 'REQUEST=paramquery&POS=12,34&SIZE=0.5&FROM=foo' \ $baseURL/async curl -d 'PHASE=RUN' $baseURL/$jobID [wait] curl $baseURL/$jobID/resultsIn this example the commonly available curl application (wget or a browser could also be used) is used to issue HTTP GET and POST requests to the remote UWS- based job manager. The query may run for an arbitrarily long time. When the job completes the output can be retrieved. Asynchronous version of our simple ADQL-based query: curl -d 'REQUEST=adqlquery&QUERY=select+*+FROM+foo' $baseURL/async curl -d 'PHASE=RUN' $baseURL/$jobID [wait] curl $baseURL/$jobID/results | |||||||
4. SimDAP Service Operations | ||||||||
Changed: | ||||||||
< < | 4.1 ListExperiments | |||||||
> > | 4.1 GetAvailability | |||||||
Changed: | ||||||||
< < | 4.1.1 Input Parameters | |||||||
> > | 4.1.1 Query Response | |||||||
Changed: | ||||||||
< < | 4.1.2 Query Response | |||||||
> > | 4.2 GetCapabilities | |||||||
Changed: | ||||||||
< < | 4.2 ListSnapshots | |||||||
> > | 4.2.1 Query Response | |||||||
Changed: | ||||||||
< < | 4.2.1 Input Parameters | |||||||
> > | 4.3 ListExperiments | |||||||
Changed: | ||||||||
< < | 4.2.1.1 EXPERIMENT | |||||||
> > | 4.3.1 Input Parameters | |||||||
Changed: | ||||||||
< < | 4.2.2 Query Response | |||||||
> > | 4.3.2 Query Response | |||||||
Added: | ||||||||
> > | 4.4 ListSnapshots | |||||||
Added: | ||||||||
> > | 4.4.1 Input Parameters | |||||||
Added: | ||||||||
> > | 4.4.1.1 EXPERIMENT4.4.2 Query Response4.5 QueryData4.5.1 Input Parameters4.5.1.1 EXPERIMENT4.5.1.2 SNAPSHOT4.5.1.3 PROPERTIES4.5.2 Query Response4.6 Cutout4.6.1 Input Parameters4.6.1.1 EXPERIMENT4.6.1.2 SNAPSHOT4.6.1.3 PROPERTIES4.6.1.4 VOLUME4.6.2 Query Response4.7 Preview4.7.1 Input Parameters4.7.1.1 EXPERIMENT4.7.1.2 SNAPSHOT4.7.1.3 PROPERTIES4.7.2 Query Response4.8 Custom4.8.1 Input Parameters4.8.1.1 EXPERIMENT4.8.1.2 SNAPSHOT4.8.1.3 PROPERTIES4.8.2 Query Response | |||||||
<--
|
Simulation Data Access Protocol (SimDAP) DraftThis page is for outlining the initial draft of the SimDAP Note. Once we've reached agreement on the outline, we will move content to an HTML version in the volute repository. Please hold of on editing this, I'm still transferring some of my notes. I should be done later today. -- RickWagner - 11 Nov 20081. Introduction2. SimDAP Data Model3. Interface Overview3.1 ArchitectureA SimDAP service provides access to initial or derived files from simulations.3.2 Service OperationsA SimDAP service implements multiple service operations, each of which performs some well defined function when invoked by a client application. The service operations described here use HTTP GET and POST as the low level communications protocol. The functionality of each operation is defined independently of the low level communications protocol, and semantically equivalent operations could be implemented in the future via other protocols. SimDAP defines the following standard service operations:
3.3 Service ProfileThe basic form of a SimDAP service is specified in detail in section ??. In the current section we merely summarize the elements of the basic service interface.3.3.1 Request FormatA service may implement multiple service operations, such as download or preview; these define the service interface. Interfaces may change with time and hence are versioned. It is possible for a given service instance to simultaneously expose multiple interfaces or versions of interfaces. The SimDAP interface described in this document is based upon a distributed computing platform (DCP) comprising Internet hosts that support the Hypertext Transfer Protocol (HTTP). Thus, the online representation of each operation supported by a service is composed as a HTTP Uniform Resource Locator (URL). A request URL is formed by concatenating a baseURL with zero or more operation-defined request parameters. The baseURL defines the network address to which request messages are to be sent for a particular operation of a particular service instance on a particular server. Service operations generally share the same baseURL but this is not required.3.4 Request Examples4. SimDAP Service Operations4.1 ListExperiments4.1.1 Input Parameters4.1.2 Query Response4.2 ListSnapshots4.2.1 Input Parameters4.2.1.1 EXPERIMENT4.2.2 Query Response<--
|