+ SPDF HOME

+ DATA & ORBITS

+ ModelWeb at CCMC

+ SCIENCE ENABLED

+ AND MORE

CDAS RESTful Web Services

Introduction

The following describe the Coordinated Data Analysis System RESTful Web services.

Target Audience

This document assumes that the reader is familar with RESTful Web service and Hypertext Transfer Protocol (HTTP) technology.

Overview

This section contains an overview of these Web services.

Entity-Body Representations

The HTTP entity-body for both the request and response messages of these services is described by a W3C XML schema document.  The detailed description of each service describes the specific XML element from the schema that is an entity-body for the specific request or response message of the service.  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.

Error Responses

This section provides a general description of error responses (i.e., a reponse with a code other than 200) that may be returned by any of the web services.  More details about the error response of specific services are provided in the specific service's description.

Any entity-body returned within an error response will be XHTML (or a JSON representation of XHTML) 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().

Note that error responses may also be generated by software components other than the web services software described here in response to requests intended for these web services.  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 web service 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 web service implementation itself.  At the time this documentation was written, the entity-body returned in an error response from both these web services and the application server hosting them 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.

Cross-Origin Resource Sharing

These web services implement the Cross-Origin Resource Sharing (CORS) mechanism.  Support for preflight requests (OPTIONS requests with Origin header) is not implemented.  This limitation should not be significant since these web services consist only of simple requests (just GET and POST).  The preflight request is only required for non-simple requests.

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:

• Java
• java.net.HttpURLConnection
• Jersy client API (com.sun.jersey.api.client)
• JAXB (javax.xml.bind)
• javax.xml
• Apache Jakarta HttpClient
  
• JavaScript
• XMLHttpRequest
  
• C/C++
• libcurl
• libxml
• ITT Interactive Data Language (IDL)
• IDLnetURL
• IDLffXMLDOM
• SPDF CDAS IDL Web Service Library
• Unix Shell Script
• cURL
• xsltproc
  

General Example Clients

• Shell Script Example.  This example should run on most Unix-like (e.g., Mac OS X, Linux, Solaris, etc.) platforms that have curl, xsltproc, and xmllint. Here is the output from running the example.
• IDL Examples.  The SPDF CDAS IDL Web Services Library contains several, complete example clients (e.g., spdfwsexample, spdfcdawebchooser, spdfgetdata).
  

Web Services

The table below summarizes the services which are available.  The table contains links to more detail descriptions of each operation.

Web Services

Category	Operation	Implementation	Details
Metadata	Get WADL	OPTIONS /	Details
	Get About Info.	GET /about
	Get Privacy Info.	GET /privacy
	Get Term Of Use Info.	Get /termsOfUse
	Get Dataviews	GET /dataviews	Details
	Get ObservatoryGroups	GET /dataviews/{dataview}/observatoryGroups? instrumentType={instrumentType}	Details
	Get IntrumentTypes	GET /dataviews/{dataview}/instrumentTypes? observatory={observatory}& observatoryGroup={observatoryGroup}	Details
	Get Intruments	GET /dataviews/{dataview}/instruments? observatory={observatory}	Details
	Get Observatories	GET /dataviews/{dataview}/observatories? instrument={instrument}& instrumentType={instrumentType}	Details
		GET /dataviews/{dataview}/description
	Get Dataset	GET /dataviews/{dataview}/datasets? observatoryGroup={observatoryGroup}& instrumentType={instrumentType}& observatory={observatory}& instrument={instrument}& startDate={startDate}& stopDate={stopDate}& idPattern={idPattern}& labelPattern={labelPattern}& notesPattern={notesPattern}	Details
	Get Inventory	GET /dataviews/{dataview}/datasets/{dataset}/inventory	Details
	Get Variables	GET /dataviews/{dataview}/datasets/{dataset}/variables	Details
Data	Get Data	POST /dataviews/{dataview}/datasets	Details
		GET /dataviews/{dataview}/datasets/{dataset}/data/ {start-time},{stop-time}/ {var1},{varn}?format={format}& options={options}& cdfVersion={cdfVersion}& thumbnailId={id}&thumbnail={num}	Details
		GET /dataviews/{dataview}/datasets/{dataset}/orig_data/ {start-time},{stop-time}/	Details

---

Get WADL

This service provides the Web Application Description Language (WADL) for these Web services.

Example

Below is an example client request to this service and the results.

$ curl --request OPTIONS http://cdaweb.gsfc.nasa.gov/WS/cdasr/1 | xmllint --format -

Get About

Get Privacy

Get Terms Of Use

Get Dataviews

This service provides descriptions of the dataviews that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Dataviews in CDAS.xsd
	Content-Type: application/json	JSON representation of Dataviews in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	406

Example

An example client request and response is provided in WsExample.sh.

Get Observatory Groups

This service provides descriptions of the observatory groups that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/observatoryGroups? instrumentType={instrumentType}
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by ObservatoryGroups in CDAS.xsd
	Content-Type: application/json	JSON representation of Dataviews in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	406

Where:

• {instrumentType} = in instrument type value (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by a Get InstrumentTypes request.  Omitting this parameter indicates that no observatories are eliminated based upon their instrumentType value.

Get Instrument Types

This service provides descriptions of the instrument types that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/instrumentTypes? observatory={observatory}& observatoryGroup={observatoryGroup}
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by InstrumentTypes in CDAS.xsd
	Content-Type: application/json	JSON representation of InstrumentTypes in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	406

Where:

• {observatory} = an observatory group value (/Observatories/ObservatoryDescription/Name) from those returned by a Get Observatories request.  Omitting this parameter indicates that no instrumentTypes are eliminated based upon their observatory value.
• {observatoryGroup} = an observatory group value (/ObservatoryGroups/ObservatoryGroupDescription/Name) from those returned by a Get ObservatoryGroups request.  Omitting this parameter indicates that no instrumentTypes are eliminated based upon their observatoryGroup value.
  

Get Instruments

This service provides descriptions of the instrument that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/instruments? observatory={observatory}
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Instruments in CDAS.xsd
	Content-Type: application/json	JSON representation of Instruments in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	406

Where:

• {observatory} = an observatory group value (/Observatories/ObservatoryDescription/Name) from those returned by a Get Observatories request.  Omitting this parameter indicates that no instruments are eliminated based upon their observatory value.

Get Observatories

This service provides descriptions of the observatories that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/observatories? instrument={instrument}& instrumentType={instrumentType}
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Observatories in CDAS.xsd
	Content-Type: application/json	JSON representation of Observatories in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	406

Where:

• {instrument} = an instrument value (/Instruments/InstrumentDescription/Name) from those returned by a Get Instruments request.  Omitting this parameter indicates that no observatories are eliminated based upon their instrument value.
• {instrumentType} = in instrument type value (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by a Get InstrumentTypes request.  Omitting this parameter indicates that no observatories are eliminated based upon their instrumentType value.

Get Datasets

This service provides descriptions of the datasets that are available from CDAS.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/datasets? observatoryGroup={observatoryGroup}& instrumentType={instrumentType}& observatory={observatory}& instrument={instrument}& startDate={startDate}& stopDate={stopDate}& idPattern={idPattern}& labelPattern={labelPattern}& notesPattern={notesPattern}
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Datasets in CDAS.xsd
	Content-Type: application/json	JSON representation of Datasets in CDAS.xsd
Most Likely Response Codes	200	Ok
	304
	404
	406

Where:

• {observatoryGroup} = an observatory group value (/ObservatoryGroups/ObservatoryGroupDescription/Name) from those returned by a Get ObservatoryGroups request.  Omitting this parameter indicates that no datasets are eliminated based upon their observatoryGroup value.
  
• {instrumentType} =ain instrument type value (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by a Get InstrumentTypes request.  Omitting this parameter indicates that no datasets are eliminated based upon their instrumentType value.
• {observatory} = an observatory group value (/Observatories/ObservatoryDescription/Name) from those returned by a Get Observatories request.  Omitting this parameter indicates that no datasets are eliminated based upon their observatory value.
• {instrument} = an instrument value (/Instruments/InstrumentDescription/Name) from those returned by a Get Instruments request.  Omitting this parameter indicates that no datasets are eliminated based upon their instrument value.
• {startDate} = a basic format (minimal number of separators) ISO 8601 date specifying the start of a time interval (e.g., 20000101T000000Z).  If this parameter is ommited, the time interval will begin infinitely in the past.
• {stopDate} = a basic format (minimal number of separators) ISO 8601 date specifying the end of a time interval (e.g., 20100101T000000Z).  If this parameter is omitted, the time interval will end infinitely in the future.
• {idPattern} = a java.util.regex compatible regular expression that must match the dataset's identifier value.  Omitting this parameter is equivalent to ".*".
• {labelPattern} = a java.util.regex compatible regular expression that must match the dataset's  label text.  Omitting this parameter is equivalent to ".*".  Embedded matching flag expressions (e.g., (?i) for case insensitive match mode) are supported and likely to be useful in this case.
• {notesPattern} = a java.util.regex compatible regular expression that must match the dataset's  notes text.  Omitting this parameter is equivalent to ".*".  Embedded matching flag expressions (e.g., (?s) for dotall match mode) are supported and likely to be useful in this case.

Additionally

• The startDate and stopDate query parameters specify an inclusive time interval such that all datasets returned have at least a portion of their data within the specified interval.
• The conditions specified by distinct query parameters are logically ANDed together.  Different values for the same query parameter are ORed together (e.g., observatory=C1&observatory=C2 means observatory is C1 or C2).  There are no provisions for expressing more general logical relationships (e.g., OR, NOT, grouping) between the query parameters (e.g., labelPattern OR notesPattern).  Individual query parameter values may support complex logical operators within the query parameter.  That is, those parameter values which are regular expressions do support all the logical operators supported the java.util.regex expression (e.g., notesPattern="(?s)(?i).*apollo(12|15).*").
  

Get Inventory

This service provides descriptions of the data inventory that is available within a dataset.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/datasets/{dataset}/inventory
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Inventory from CDAS.xsd
	Content-Type: application/json	JSON representation of Inventory
Most Likely Reponse Codes	200	Ok
	304	Not Modified
	404	Not Found
	406	Not Acceptable
	415	Unsupported Media Type

Get Variables

This service provides descriptions of the variables that is available from a dataset.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/datasets/{dataset}/variables
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by Variables from CDAS.xsd
	Content-Type: application/json	JSON representation of Variables
Most Likely Reponse Codes	200	Ok
	304	Not Modified
	404	Not Found
	406	Not Acceptable
	415	Unsupported Media Type

Get Data (POST)

This service provides data from a dataset.  The data is available in various representations (CDF, text, graph).  The following table describes the HTTP request and response.

HTTP Method		POST
URI		/dataviews/{dataview}/datasets/
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since	This is only meaningful when original CDF files are being requested.
Request Entity		As specified by DataRequest in CDAS.xsd
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by DataResult in CDAS.xsd
	Content-Type: application/json	JSON representation of DataResult
Most Likely Reponse Codes	200	Ok
	304	Not Modified
	404	Not Found
	406	Not Acceptable
	415	Unsupported Media Type

Get Data (GET)

This service provides data from a dataset.  The data is available in various representations (CDF, text, graph).  This operation offers a subset of the features available in the corresponding POST operation.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/datasets/{dataset}/data/ {start-time},{stop-time}/ {var1},{varn}?format={format}& options={options}& cdfVersion={cdfVersion}& &thumbnailId={id}&thumbnail={num} see notes below for further details
Significant Request Headers	Accept	application/xml
		application/json
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by DataResult in CDAS.xsd
	Content-Type: application/json	JSON representation of DataResult
Most Likely Reponse Codes	200	Ok
	304	Not Modified
	400	Bad Request (refer to entity-body for specifics)
	404	Not Found
	406	Not Acceptable
	415	Unsupported Media Type

Notes:

• This GET operation offers a subset of the features available in the corresponding POST operation.  It is intended for cases where the POST operation is not practical.  The specific limitations are as follows:
  
• Does not support SPASE ResourceIDs in place of CDAS dataset names.
  
• Does not support multi-dataset resources.
  
• Does not accept multiple time intervals.
• start-time is the beginning time of an interval in basic (minimal number of separators) ISO 8601 format.  Extended ISO 8601 format is not allowed.
• stop-time is the ending time of an interval in basic (minimal number of separators) ISO 8601 format.  Extended ISO 8601 format is not allowed.
• var1,varn are the comma separated list of variable names identifying the data to get. The names should be from those returned by the Get Variables operation. At least one variable name must be specified when format=text, format=gif, format=png, format=ps, or format=pdf. When format=cdf, you may use ALL-VARIABLES instead of specifying all the individual variable names.
• format is the output representation of the requested data:
• cdf requests the data in the binary CDF file format (any other format options are ignored).
  
• text requests the data in an ASCII text representation (any other format options are ignored).
  
• Request the data in a graphical representation.  The actual format value is any or all of the following:
  
• gif
  
• png
  
• ps
  
• pdf
  
• cdfVersion is the CDF file version that any created CDF files should be (2 or 3).  This value is ignored for any format value other than CDF.
  
• options is an integer value defined by a bitwise inclusive OR of the following values:
• 0x1 => use coarse noise filtering to remove values outside 3 deviations from mean of all
  values in the plotted time interval
• 0x2 => double the Y-axis height for time-series and spectrogram plots
• thumbnailId is the value that was returned by a previous call that returned an image of thumbnail images.  This parameter should not be given for calls that are not requesting the expansion of a thumbnail image.
  
• thumbnail is the number of the thumbnail whose expanded image is now being requested.  Thumbnail images are counted beginning at one (not zero).  This parameter should not be given for calls that are not requesting the expansion of a thumbnail image.

Get Original Data (GET)

This service provides original data files from a dataset.  The following table describes the HTTP request and response.

HTTP Method		GET
URI		/dataviews/{dataview}/datasets/{dataset}/orig_data/ {start-time},{stop-time}/ see notes below for further details
Significant Request Headers	Accept	application/xml
		application/json
	If-Modified-Since	Only get files that have been modified since this date.
Request Entity	none
Significant Response Headers	Last-Modified
Response Entity	Content-Type: application/xml	As specified by DataResult in CDAS.xsd
	Content-Type: application/json	JSON representation of DataResult
Most Likely Reponse Codes	200	Ok
	304	Not Modified
	400	Bad Request (refer to entity-body for specifics)
	404	Not Found
	406	Not Acceptable
	415	Unsupported Media Type

Notes:

• This GET operation offers a subset of the features available in the corresponding POST operation.  It is intended for cases where the POST operation is not practical.  The specific limitations are as follows:
  
• Does not support SPASE ResourceIDs in place of CDAS dataset names.
  
• Does not support multi-dataset resources.
  
• Does not accept multiple time intervals.
• start-time is the beginning time of an interval in basic (minimal number of separators) ISO 8601 format.  Extended ISO 8601 format is not allowed.
• stop-time is the ending time of an interval in basic (minimal number of separators) ISO 8601 format.  Extended ISO 8601 format is not allowed.

Questions/Comments

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