NASA Logo, National Aeronautics and Space Administration

SSC RESTful Web Services

Introduction

The following describe the Satellite Situation Center 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.

Notice
Since November 2013 when the JAX-RS provider we use changed JAXB providers, the JSON support in these web services has not functioned.  While the new JAXB provider claims to support JSON, it has not worked in our case.  The documentation below still describes JSON support because we hope to support it again in the future.  But JSON support with the current JAX-RS/JAXB providers has gotten progressively worse with subsequent releases so it is uncertain when we will be able to support JSON again.

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

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

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:

Software Development Kit (SDK)

The SSC REST SDK consists of documentation, example code, and pre-compiled client libraries that may be helpful to client developers. The SDK is available for download here.

Example Clients

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
GET /application.wadl /
Details
Get Observatories
GET /observatories
Details
Get SPASE Observatories
GET /spaseObservatories
Details
Get GroundStations
GET /groundStations
Details
Data


Get Locations
POST /locations
Details
Get Graphs
POST /graphs
Details
Get Conjunctions
POST /conjunctions
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 http://sscweb.gsfc.nasa.gov/WS/sscr/2/application.wadl | xmllint --format -


Get Observatories

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

HTTP Method

GET
URI

/observatories
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 ObservatoryResponse in SSC.xsd
Content-Type: application/json
JSON representation of ObservatoryResponse in SSC.xsd
Most Likely Response Codes
200
Ok
304

406



Get SPASE Observatories

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

HTTP Method

GET
URI

/spaseObservatories
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 ObservatoryResponse in SSC.xsd
Content-Type: application/json
JSON representation of ObservatoryResponse in SSC.xsd
Most Likely Response Codes
200
Ok
304

406



Get Ground Stations

This service provides descriptions of the ground stations that are available from SSC.  The following table describes the HTTP request and response.

HTTP Method

GET
URI

/groundStations
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 GroundStationDescription in SSC.xsd
Content-Type: application/json
JSON representation of GroundStationDescription in SSC.xsd
Most Likely Response Codes
200
Ok
304

404

406




Get Locations (POST)

This service provides observatory location information.  The following table describes the HTTP request and response.

HTTP Method

POST
URI

/locations
Significant Request Headers
Accept

application/xml
application/json
Request Entity

As specified by DataRequest in SSC.xsd
Significant Response Headers
Last-Modified

Response Entity

Content-Type: application/xml
As specified by DataResult in SSC.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 Graphs (POST)

This service provides observatory location graphs.  The following table describes the HTTP request and response.

HTTP Method

POST
URI

/graphs
Significant Request Headers
Accept

application/xml
application/json
Request Entity

As specified by GraphRequest in SSC.xsd
Significant Response Headers
Last-Modified

Response Entity

Content-Type: application/xml
As specified by LocationFileResult in SSC.xsd
Content-Type: application/json
JSON representation of LocationFileResult
Most Likely Reponse Codes
200
Ok

304
Not Modified

404
Not Found

406
Not Acceptable

415
Unsupported Media Type


Get Conjunctions (POST)

This service provides results of a conjunction query.  The following table describes the HTTP request and response.

HTTP Method

POST
URI

/conjunctions
Significant Request Headers
Accept

application/xml
application/json
Request Entity

As specified by QueryRequest in SSC.xsd
Significant Response Headers
Last-Modified

Response Entity

Content-Type: application/xml
As specified by QueryResult in SSC.xsd
Content-Type: application/json
JSON representation of QueryResult
Most Likely Reponse Codes
200
Ok

304
Not Modified

404
Not Found

406
Not Acceptable

415
Unsupported Media Type


Questions/Comments

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

NASA Logo - nasa.gov