+ SPDF HOME

+ MISSION DATA

+ ModelWeb at CCMC

+ SCIENCE ENABLED

+ AND MORE

HDP RESTful Web Services

Introduction

The following describe the Heliophysics Data Portal RESTful Web services. These web services allow a software developer to query the HDP Space Physics Archive Search and Extract (SPASE) database. If you are not a software developer, you probably want to use the Heliophysics Data Portal itself.

• Target Audience
• Overview
• Client Access Mechanisms

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.

These web services are described by an OpenAPI specification document.

These web services mainly assist in identifying Heliophysics data. To access the data, see the //spase:AccessInformation element of the returned metadata.

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:

• 
• hdpws
  • hdpws at the PyPI respository.
  • hdpws at the 
  • Jupyter Notebook Examples: 
    • Simple Example (ipynb file).
    • Example with data retrieval using cdasws (ipynb file).
    • Example with data retrieval using sscws (ipynb file).
    • HAPI Example (ipynb file).
    • HAPI Example with data retrieval (ipynb file).

cURL Examples

The following are a few cURL example requests. $ curl "https://heliophysicsdata.gsfc.nasa.gov/WS/hdp/1/Spase/MeasurmentType" $ curl -H "Accept: application/json" "https://heliophysicsdata.gsfc.nasa.gov/WS/hdp/1/Spase/SpectralRange" $ curl "https://heliophysicsdata.gsfc.nasa.gov/WS/hdp/1//Spase/NumericalData/1972-01-01,1972-01-05?ResourceID=spase://NASA/NumericalData/Apollo12-LM/SWS/PT1HR&InstrumentID=spase://SMWG/Instrument/Apollo12-LM/SWS&Format=CDF&AccessRights=Open&ObservedRegion=Heliosphere.NearEarth&MeasurementType=ThermalPlasma&Cadence=>PT30M&Style=WebService"

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").

JSON Support
Anyone considering using JSON, should read this page first.

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 and allow cross-origin access from any domain.

Questions/Comments

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