The following describe the Heliophysics Event List Manager (HELM) RESTful Web services.
This document assumes that the reader is familar with RESTful Web service and Hypertext Transfer Protocol (HTTP) technologies.
This section contains an overview of these Web services.
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”).
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. To diagnose a 404 response generated by the Jersey framework, the client should add an X-Jersey-Trace-Accept HTTP request header with any value to the request. This will cause the 404 response to have X-Jersey-Trace-nnn headers that will describe the failed attempts to match the request to a Web service implementation.
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.
curl, xsltproc, and xmllint. Here is the output from running the example.java.net.HttpURLConnection.com.sun.jersey.api.client).The table below summarizes the services which are available. The table contains links to more detail descriptions of each operation.
Web Services
| Operation | Implementation | Details |
|---|---|---|
| Get WADL | OPTIONS / | Details |
| Get About Info. | GET /about | |
| Get Privacy Info. | GET /privacy | |
| Get Terms of Use Info. | GET /termsOfUse | |
| Get an Eventlist | GET /eventlists/{listname: [a-zA-Z][a-zA-Z_0-9]*} | Details |
| Get keywords | GET /eventlists/keywords?pattern={pattern} | Details |
| Search Eventlists | GET /eventlists?keyword={keyword}&xpathp={xpathp} | Details |
| Eventlist Union | GET /union?listUrl={listUrl} | Details |
| Eventlist Intersection | GET /intersection?listUrl={listUrl} | Details |
| Shift Times of Eventlist | GET /shiftTimes?quantity={quantity}&listUrl={listUrl} | Details |
| POST /shiftTimes?quantity={quantity} | Details | |
| Adjust TimeSpans of Eventlist | GET /adjustTimeSpans?quantity={quantity}&listUrl={listUrl} | Details |
| POST /adjustTimeSpans?quantity={quantity} | Details |
This service provides the Web Application Description Language (WADL) for these Web services.
Below is an example client request to this service and the results.
$ curl —request OPTIONS http://helm.gsfc.nasa.gov/WS/helm/1/ | xmllint —format -
Retrieves the specified Eventlist.
| HTTP Method | GET | |
|---|---|---|
| URI | /eventlists/{listname:[a-zA-Z][a-zA-Z_0-9]*} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| If-Modified-Since | ||
| Request Entity | none | |
| Significant Response Headers | Last-Modified | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | Ok |
| 304 | Not Modified | |
| 404 | Not Found |
Where:
[a-zA-Z][a-zA-Z_0-9]*.Retrieves Eventlist keyword values.
| HTTP Method | GET | |
|---|---|---|
| URI | /eventlists/keywords?pattern={pattern} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| application/xhtml+xml | ||
| If-Modified-Since | ||
| Request Entity | none | |
| Significant Response Headers | Last-Modified | |
| Reponse Entity | Content-Type: application/xml | As specified by KeywordDescriptions in helm.xsd |
| Content-Type: application/json | JSON representation of KeywordDescriptions in helm.xsd | |
| Most Likely Response Codes | 200 | Ok |
| 304 | Not Modified | |
| 404 | Not Found |
Where:
Searchs all Eventlists for those that satisfies the given criteria and returns a description those Eventlists.
| HTTP Method | GET | |
|---|---|---|
| URI | /eventlists?keyword={keyword}&xpathp={xpathp} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| application/xhtml+xml | ||
| Request Entity | none | |
| Reponse Entity | Content-Type: application/xml | As specified by EventlistDescriptions in helm.xsd |
| Content-Type: application/json | JSON representation of EventlistDescriptions in helm.xsd | |
| Content-Type: application/xhtml+xml | A very basic XHTML page with an unordered list (
| |
| Most Likely Response Codes | 200 | 0 |
| 400 | 0 | |
| 404 |
Where:
{keyword} is an Eventlist/spase:Keyword value that selects the desired eventlist.
{xpathp} is any XPath 2.0 expression that selects the desired eventlist. For example, “//spase:PhenomenonType[text()=‘GeomagneticStorm’]” URL encoded as “%2F%2Fspase%3APhenomenonType%5Btext%28%29%3D%27GeomagneticStorm%27%5D” would retrieve all Eventlists with PhenomenonType==GeomagneticStorm.
Multiple keyword values are logically ANDed together.
Performs a union of the specified Eventlists and returns the resulting Eventlist.
| HTTP Method | GET | |
|---|---|---|
| URI | /union?listUrl={listUrl} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | none | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | |
| 400 | ||
| 404 |
Where:
{listURL} is a URL identifying the Eventlist for the union operation. At least two values must be provided.
Performs an intersection of the specified Eventlists and returns the resulting Eventlist.
| HTTP Method | GET | |
|---|---|---|
| URI | /intersection?listUrl={listUrl} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | none | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | 0 |
| 400 | 0 | |
| 404 |
Where:
{listURL} is a URL identifying the Eventlist for the intersection operation. At least two values must be provided.
Adds the specified quantity to each StartDate and StopDate within the given Eventlist and returns the resulting Eventlist.
| HTTP Method | GET | |
|---|---|---|
| URI | /shiftTimes?listUrl={listUrl}&quantity={quantity} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | none | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | |
| 400 | ||
| 404 |
Where:
{listURL} is a URL identifying the Eventlist for the time-shift operation.
{quantity} is an ISO 8601 Duration value that is to be added to each Eventlist/Event/TimeSpan/StartDate and Eventlist/Event/TimeSpan/StopDate value within the specified Eventlist. The Duration value may be positive or negative.
Adds the specified quantity to each StartDate and StopDate within the given Eventlist and returns the resulting Eventlist.
| HTTP Method | POST | |
|---|---|---|
| URI | /shiftTimes?quantity={quantity} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | As specified by Eventlist in helm.xsd | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | |
| 400 | ||
| 404 |
Where:
{quantity} is an ISO 8601 Duration value that is to be added to each Eventlist/Event/TimeSpan/StartDate and Eventlist/Event/TimeSpan/StopDate value within the specified Eventlist. The Duration value may be positive or negative.
Symmetrically widens or narrows all TimeSpan values in the specified Eventlist by the specified quantity and returns the resulting Eventlist.
| HTTP Method | GET | |
|---|---|---|
| URI | /adjustTimeSpans?listUrl={listUrl}&quantity={quantity} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | none | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | |
| 400 | ||
| 404 |
Where:
{listURL} is a URL identifying the Eventlist for the TimeSpan-adjustment operation.
{quantity} is an ISO 8601 Duration value that is to widen/narrow each Eventlist/Event/TimeSpan value within the specified Eventlist. The Duration value may be positive or negative. Half of the Duration value is subtracted from the each Eventlist/Event/TimeSpan/StartDate value and half of the Duration value is added to the Eventlist/Event/TimeSpan/StopDate value.
Symmetrically widens or narrows all TimeSpan values in the provided Eventlist by the specified quantity and returns the resulting Eventlist.
| HTTP Method | POST | |
|---|---|---|
| URI | /adjustTimeSpans?quantity={quantity} | |
| Significant Request Headers | Accept | application/xml |
| application/json | ||
| Request Entity | As specified by Eventlist in helm.xsd | |
| Reponse Entity | Content-Type: application/xml | As specified by Eventlist in helm.xsd |
| Content-Type: application/json | JSON representation of Eventlist in helm.xsd | |
| Most Likely Response Codes | 200 | |
| 400 | ||
| 404 |
Where:
Eventlist/Event/TimeSpan value within the specified Eventlist. The Duration value may be positive or negative. Half of the Duration value is subtracted from the each Eventlist/Event/TimeSpan/StartDate value and half of the Duration value is added to the Eventlist/Event/TimeSpan/StopDate value.Questions or comments concerning these Web services should be sent to HELM Feedback.