Operation

This document describes how to operate the Transport Service software contained in the transport-registry package. The Transport Service software is a web application for retrieving product files from the the Product Servers that are located at the various Discipline Nodes. The following topics can be found in this section:

Interface

The Transport Service provides a REST-based interface accessible via HTTP for interacting with the service. Because the REST-based interface operates over HTTP, there are several options for interacting with the Transport Service:

  • Web Browser

    Any standard web browser (e.g., Firefox, Safari, Chrome, Internet Explorer, etc.) will allow interaction with the service.

  • cURL

    The cURL utility offers the most flexible means for interacting with the application. The utility comes installed on most UNIX-based platforms and is available for download for the Windows platform. The examples in the sections that follow utilize cURL to interact with the application. If cURL is not installed on the local machine but Wget is, see the Using Wget section for converting cURL commands to Wget commands.

The examples below use http://localhost:8080 as the default base end point for the service.

Product Retrieval

The Transport Service web application provides functionality for querying the Registry Service for a product or products and retrieving the associated files. The service can be queried using 3 possible methods for encoding the HTTP request parameters: DIS-Style syntax, XML query expressions, or simple HTTP (name, value) pairs. The following table summarizes the parameters available:

HTTP ParameterDescription
qThe DIS-Style query expression identifying the product (or set of files) to retrieve from the Transport Service. The use of the q parameter is preferred over the use of the xmlq parameter, but it is still discouraged with respect to the use of straight HTTP (name, value) pairs (last option in this table). Additional information regarding the DIS-Style query format can be found at the Apache OODT DIS-Style Query page.
xmlqThe XML query expression identifying the product (or set of files) to retrieve from the Transport Service. The details for the format of this query expression will not be covered here. Although supported, the use of the xmlq parameter is discouraged.
identifier, packageThe product identifier (specified one or more times), and the requested packaging format (ZIP, TGZ, ZIP_SIZE, TGZ_SIZE). This is the preferred method to query the transport-registry service.

When using DIS-Style format, the identifier and package parameters must be encoded as part of the "q" value parameter:

DIS Query ParameterDescription
identifierThe identifier for the product to be retrieved in the form of a PDS logical identifier (LID) or the LID and the version identifier (LIDVID). This parameter is required and may be specified more than once. Due to the 5000 character limit for HTTP POST commands, a safe maximum of specified identifiers is around 50.
packageThe package type to be returned from the Transport Service. The valid values are ZIP, TGZ to return the compressed packages, and ZIP_SIZE, TGZ_SIZE to return the total size of all contained files once the compressed packages are expanded. The values are not case sensitie. The default value is ZIP. This parameter is optional.

The following is an example query using DIS-Style query syntax with the q parameter: 

% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?q=identifier+EQ+<LID|LIDVID>

Assuming the LID or LIDVID was specified correctly, the above query should return a ZIP package containing the products associated with the specified product. The following is an example query in DIS-Style syntax that will return a TAR/GZIP package: 

% curl -X GET -o package.tar.gz -v \
http://localhost:8080/transport-registry/prod?q=identifier+EQ+<LID|LIDVID>+AND+package+EQ+TGZ

Alternatively, the product identifier and desired packaging can be specified using standard HTTP parameter encoding. The general URL form is:

http://localhost:8080/transport-registry/prod?identifier=<LID|LIDVID>&package=<TGZ|ZIP|TGZ_SIZE|ZIP_SIZE>

For example, the following URLs specify the same logical request for retrieving a PDS product: 

http://localhost:8080/transport-registry/prod?q=identifier+EQ+\
urn:nasa:pds:phx_lidar:reduced:LS075RLS_00902835894_1885M1+AND+package+EQ+TGZ
or: 
http://localhost:8080/transport-registry/prod?identifier=\
urn:nasa:pds:phx_lidar:reduced:LS075RLS_00902835894_1885M1&package=TGZ
(again assuming the product exists).

The following queries return an XML document containing the size of the uncompressed TGZ/ZIP packages respectively (which, once expanded, have obviously the same size): 

http://localhost:8080/transport-registry/prod?identifier=\
urn:nasa:pds:phx_lidar:reduced:LS147RLA_00909259320_204CM1&package=TGZ_SIZE
	
http://localhost:8080/transport-registry/prod?identifier=\
urn:nasa:pds:phx_lidar:reduced:LS147RLA_00909259320_204CM1&package=ZIP_SIZE