NASA Logo, National Aeronautics and Space Administration

CDAS SPASEQL Web Services

Introduction

The following describe the Coordinated Data Analysis System's Space Physics Archive Search and Extract (SPASE) Query Language (SPASEQL) Web API.

Target Audience

This document is intended for client web application developers.  It assumes that the reader is familar with the following technologies:

Overview

This section contains an overview of these Web services.  Note that these web services provide a very limited implementation of SPASEQL as described below.

Web Services

To access these web services, send an HTTP POST request to
http://cdaweb.gsfc.nasa.gov/WS/spaseql/1/Query
with the entity-body containing a SPASEQL query request  supported by these web services.  The entity-body of non-error (response code 200) HTTP responses will contain a SPASEQL response.  The NumericalData resources currently supported by these web services can be viewed here.   The queries supported by these web services and the responses are further described below.

Query Requests

These web services support SPASEQL queries that contain the following SPASEQL/Request/Select/SPASEQLTerm values:
Each of these queries and their responses are described below.

Inventory

An Inventory query is used to obtain data availability information for a dataset identified by its SPASE NumericalData ResourceID.  The only SPASEQL/Request/Where/Clause/Expression currently supported is one containing a single ResourceID/Equal value.  Below is an example SPASEQL Request to obtain the inventory of the Geotail KP Magnetic Field dataset.


The results for the above query are shown below.




GetParameterList Query

A GetParameterList query is used to obtain a list of the SPASE Parameters contained in a dataset identified by its SPASE NumericalData ResourceID.  The only SPASEQL/Request/Where/Clause/Expression currently supported is one containing a single ResourceID/Equal value.  Below is an example SPASEQL Request to obtain the Parameters of the Geotail KP Magnetic Field dataset.


The results for the above query are shown below.




GranuleURL Query

A GranuleURL query is used to obtain the URL of a SPASE granule.   The only SPASEQL/Request/Where/Clause/Expressions currently supported are the following: value.  Below is an example SPASEQL Request to obtain the URL of an ASCII listing of the values of the Parameter named IB between the times 1999-01-01 00:00:00 and 1999-01-01 00:05:00 in the Geotail KP Magnetic Field dataset.


The results for the above query are shown below.



Entity-Body Representations

The HTTP entity-body for both the request and response messages of these services is described by SPASEQL and CDAS  W3C XML schema documents.  In addition to the XML representation of the entity-body, all the services can return the entity-body in a mapped (with root unwrapping) JSON representation of the XML object.  A client can express their preference for a specific entity-body representation (XML or JSON) by setting the HTTP accept header (to "application/xml" or "application/json").  Presently, due to a limitation with the JSON parser that is being used by the services, they cannot accept JSON representations for entity-bodies in requests.  It is hoped that in the future, the web services will also be able to accept JSON representations of entity-bodies.

HTTP Responses

This section provides a general description of HTTP responses.  The table below summarizes the HTTP responses that a client might recieve.

Code
 Source
 Entity-Body
 Comments
MIME-type
 Contents
1xx
 Web


200
 SPASEQL
 application/xml
application/json
 SPASEQL response
 Specifics are dependant upon the request.
201


Not used (even in the case where a resource was created in response to the request).
3xx
 Web


400
 SPASEQL & Web
 application/xhtml+xml
application/json
 XHTML
JSON
 A JSON representation of XHTML is only available for messages originating from the SPASEQL implementation and only if the client requests JSON.
4xx
 Web
 application/xhtml+xml
 XHTML
 404 and 415 are the most likely codes.
500
 SPASEQL & Web
 text/plain
 stack trace
 Although the SPASEQL implementation attempts to provide the client with a more meaningful XHTML description of the problem, the current Web infrastructure software replaces it with a strack trace.
5xx
 Web



Column 1 above contains the HTTP response status code.  Column 2 contains identifies the source responsible for the creating the response.  The source is either the Web infrastructure (HTTP Proxies and Web Application Servers) or the SPASEQL implementation.  Column 3 identifies the MIME-type of the response.  Column 4 further describes the content of the entity-body.  Column 5 contains a comment further clarifying the response.

Note that it is possible to recieve an OK (code 200) HTTP response that contains a SPASEQL error message in /SPASEQL/Messages/ErrorMessage or a CDAS application error message in /SPASEQL/ResultSet/Result/cdas:DataResult/cdas:Error.

Code 400 error responses orginating from the SPASEQL implementation will contain an XHTML (or a JSON representation of XHTML) entity-body that contains a more detailed description of the error.  Whether the entity-body is XHTML or JSON depends upon the HTTP Accept header in the request.  Not all error responses will contain an entity-body.  A client may simply display the XHTML or access the more detailed error message within the XHTML at  //p[class='ErrorMessage']/text() and  //p[class='ErrorDescription']/text().

Error responses may  be generated by software components other than the SPASEQL implementation described here.  For example, a request with an invalid URI path may result in a response (e.g., 404) that is generated by the application server instead of by the web service software.  In fact, different invalid URI paths may result in an error response being generated by a proxy server, the web application server, the web service framework, or the SPASEQL implementation itself.  The entity-body in an error response will vary depending upon the software component that generates the response.  A client must be prepared to deal with these differences.  The above description of an entity-body in an error response only describes those generated by the SPASEQL implementation itself.  At the time this documentation was written, the entity-body returned in an error response from both the SPASEQL implementation and the application server were similar.  The  //p[class='ErrorMessage']/text() value described above is accessible by //p[2]/text() in the error response from both these web services and their hosting application server.  Likewise, the //p[class='ErrorDescription']/text() value described above is accessible by //p[3]/text() in the error response from both these web services and their hosting application server.

Client Access Libraries

To access these web services, a client merely needs the ability to send and receive HTTP requests and responses as well as the ability interpret XML or JSON messages.  Most programming languages and environments have these capabilities.  In fact, most programming environments have several, competing implementations of these capabilities.  This section does not attempt to list all the alternatives for creating clients that access these services.  Below are just a few of the mechanisms that can be used by clients to access these web services:

General Example Clients

Questions/Comments

Questions or comments concerning these Web services should be sent to CDAS Feedback.

NASA Logo - nasa.gov