NASA Logo, National Aeronautics and Space Administration

CDAS RESTful Web Services

Notice
For two decades, there was also a Simple Object Access Protocol (SOAP) version of the CDAS web services, but they were eliminated in March 2024 due to lack of computer industry support.

Introduction

The Coordinated Data Analysis System (CDAS) supports simultaneous multi-mission, multi-instrument selection and comparison of science data among a wide range of current space missions.  While CDAWeb provides access to this data through an HTML-based user interface, these Web services provides a (Web) application programmming interface (API) to CDAS. If you are not a software developer and simply want to use the existing web (HTML) interface to CDAS, then return to the main CDAWeb page. If you are developing an application that requires science data from any of the data sets held by CDAS, then the CDAS Web services will provide an interface to the data for your application.  They are implement as Representational State Transfer (REST) style web services and are described below.

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.

Network Protocol Support

The following web services are currently available over HTTP/1.1 with TLS and both IPv4 and IPv6. Additional information about accessing these web services over HTTPS is available at HTTPS SPDF 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 (diagram).  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").  Examples of JSON requests and responses are described here.

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 application firewall, the web application server, the web service framework, or the 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 to allow JavaScript AJAX calls from within a browser from any domain. 

Client Access Mechanisms

To access these web services, a client merely needs the ability to send and receive HTTP requests and responses as well as the ability to 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:

Example URLs

The following are example URLs.

Note: These example URLs produce XML (or JSON) which may not display well in all browsers. You may want to enable the browser's "developer mode", install an extension for viewing XML (or JSON), or use a tool other than a browser.

Web Services

The table below summarizes the services which are available.  Only the last part of the URL's path is shown in the table.  The beginning part of the URL is
The table contains links to more detail descriptions of each operation.

Web Services
Category
 Operation
 Implementation
 Details
Metadata
 Get WADL
 GET /application.wadl
 Details
Get Dataviews
 GET /dataviews
 Details
Get ObservatoryGroups
 GET /dataviews/{dataview}/observatoryGroups?
instrumentType={instrumentType}
 Details
Get InstrumentTypes
 GET /dataviews/{dataview}/instrumentTypes?
observatory={observatory}&
observatoryGroup={observatoryGroup}
 Details
Get Instruments
 GET /dataviews/{dataview}/instruments?
observatory={observatory}&
instrumentType={instrumentType}
 Details
Get Observatories
 GET /dataviews/{dataview}/observatories?
instrument={instrument}&
instrumentType={instrumentType}
 Details
Get ObservatoryGroupsAndInstruments GET /dataviews/{dataview}/observatoryGroupsAndInstruments?
instrumentType={instrumentType}
 Details
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/
{start-time},{end-time} 		Details
Get Variables
 GET /dataviews/{dataview}/datasets/{dataset}/variables
 Details
Get Client Example
 GET /dataviews/{dataview}/datasets/{dataset}/clientLibraryExample/{library}?mediaType={mediaType}
 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 https://cdaweb.gsfc.nasa.gov/WS/cdasr/1/application.wadl?detail | xmllint --format -

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
 Not Modified
406
 Not Acceptable

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 ObservatoryGroups in CDAS.xsd
Most Likely Response Codes
 200
 Ok
304
 Not Modified
406
 Not Acceptable

Where:

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
 Not Modified
406
 Not Acceptable

Where:

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}&
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 Instruments in CDAS.xsd
Content-Type: application/json
 JSON representation of Instruments in CDAS.xsd
Most Likely Response Codes
 200
 Ok
304
 Not Modified
406
 Not Acceptable

Where:

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
 Not Modified
406
 Not Acceptable

Where:

Get Observatory Groups and Instruments

This service provides descriptions of the observatory groups (and associated instruments) that are available from CDAS.  This is a convenience/performance alternative to making multiple calls to Get Observatory Groups, Get Observatories, and Get Instruments.  The following table describes the HTTP request and response.

HTTP Method
GET
URI
/dataviews/{dataview}/observatoryGroupsAndInstruments?
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 ObservatoryGroupInstruments in CDAS.xsd
Content-Type: application/json
 JSON representation of Dataviews in CDAS.xsd
Most Likely Response Codes
 200
 Ok
304
 Not Modified
406
 Not Acceptable

Where:

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
 Not Modified
404
 Not Found
406
 Not Acceptable

Where:
Additionally

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/
{start-time},{end-time}
see notes below for further details
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

Notes:


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 Client Example

This service provides example client code to retrieve data from a dataset.  The following table describes the HTTP request and response.

HTTP Method
GET
URI
/dataviews/{dataview}/datasets/{dataset}/clientLibraryExample/{library}?mediaType={mediaType}
Significant Request Headers
 Accept
 application/xhtml+xml
application/octet-stream
text/plain
text/x-python
text/x-idl
If-Modified-Since
Request Entity
 none
Significant Response Headers
 Last-Modified
Response Entity

 Content-Type: application/xhtml+xml
 An XHTML page containing example code for the specified client library to retrieve data from the specified dataset.
Content-Type: text/plain, text/x-python, text/x-idl, application/octet-stream Example code for the specified client library to retrieve data from the specified dataset.
Most Likely Reponse Codes
 200
 Ok
304
 Not Modified
404
 Not Found
406
 Not Acceptable

Notes:


Get Data (POST)

This service provides data from a dataset.  The data is available in various representations (CDF, text, graph).

Note: In the case of a request for a non-original (that is, subsetted/supersetted) CDF (or CDFML) file involving a dataset whose variable names are not legal IDL variable names, the variable names in the resulting CDF (or CDFML) file will have their names changed to legal IDL variable names. For example, a request for a subsetted FA_K0_TMS CDF file will result in a file where the original H+ variable name has been changed to H$.

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 Only return the data if the underlying files have been modified since the specified date.
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
429
 Too Many Requests. Check Retry-After header value.
503
 Service Unavailable. Check Retry-After header value.

Example

Below is an example client request to this service and the results.
$ curl --silent -H "Content-Type: application/xml" \
    -H "Accept: application/xml" \
    --data-ascii @Request.xml \
    https://cdaweb.gsfc.nasa.gov/WS/cdasr/1/dataviews/sp_phys/datasets \
    | xmllint --format -
Where Request.xml is


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. 

Note: In the case of a request for a non-original (that is, subsetted/supersetted) CDF (or CDFML) file involving a dataset whose variable names are not legal IDL variable names, the variable names in the resulting CDF (or CDFML) file will have their names changed to legal IDL variable names. For example, a request for a subsetted FA_K0_TMS CDF file will result in a file where the original H+ variable name has been changed to H$.

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
If-Modified-Since Only return the data if the underlying files have been modified since the specified 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
429
 Too Many Requests. Check Retry-After header value.
503
 Service Unavailable. Check Retry-After header value.

Notes:


Get Original Data (GET)

This service provides original data files from a dataset.  Original data files may lack updated meta-data and virtual variable values contained in files obtained from the other Get Data services. 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 return the data if the underlying files have been modified since the specified 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:

Questions/Comments

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

NASA Logo - nasa.gov