Software Documentation
Download
Project Documentation
This document describes how to operate the Registry Service software. The following topics can be found in this document:
The Registry Service provides a REST-based interface accessible via HTTP for interacting with the service. Details on the REST-based interface can be found in the API document. The API documentation is also available from any deployed instance of the Registry Service by accessing /registry/docs/ from the host application server. Because the REST-based interface operates over HTTP, there are several options for interacting with the Registry Service:
The registry-ui component offers a Graphical User Interface (GUI) for interacting with the service.
Any standard web browser (e.g., Firefox, Safari, Internet Explorer, etc.) will allow interaction with the query and retrieval interfaces of the service.
The cURL utility offers the most flexible means for interacting with the service. 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 service. If cURL is not installed on the local machine but Wget is, see the Using Wget section for converting cURL commands to Wget commands. If viewing this document in PDF form, see the appendix for details.
The Registry Service also allows messaging (acceptance of and return of content descriptions) in the form of XML or JavaScript Object Notation (JSON). More on this in the examples below. Each PDS Node will have their own installation of the Registry Service with its own service URL location. Because of this, the examples below use http://localhost:8080 as the generic URL location for the service.
The Registry Service supports a wide range of artifacts for registration with the service. In ebXML terms, artifacts are referred to as Registry Objects. The following subsections provide examples for each of the supported Registry Object types.
In PDS terms, an extrinsic can be a data product, document, element definition, mission description, schema, etc. Within the ebXML terminology this maps to an Extrinsic Object which is simply a way for a particular instantiation of a registry to extend its model. The following is an example of an extrinsic description in XML form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<extrinsicObject xmlns="http://registry.pds.nasa.gov"
guid="1234v1.0"
lid="1234"
name="Product 1234 v1"
objectType="Product"
description="This is a new version test product 1234 v1" >
<slot name="first-name">
<value>John</value>
</slot>
<slot name="last-name">
<value>Doe</value>
</slot>
<slot name="phone">
<value>(818)123-4567</value>
<value>(818)765-4321</value>
</slot>
</extrinsicObject>
The extrinsic description above is contained in the new_product.xml file, which can be found in the /examples directory of the software distribution package. The following command registers this extrinsic with the service:
% curl -X POST -H "Content-type:application/xml" -v -d @new_product.xml \
http://localhost:8080/registry/extrinsics
A successful registration with the above command would produce the following output to standard out:
* About to connect() to localhost port 8080 (#0)
* Trying ::1... Connection refused
* Trying fe80::1... Connection refused
* Trying 127.0.0.1... connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
> POST registry/extrinsics HTTP/1.1
> User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) ...
> Host: localhost:8080
> Accept: */*
> Content-type:application/xml
> Content-Length: 598
>
< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: http://localhost:8080/registry/extrinsics/1234v1.0
< Content-Type: application/xml
< Content-Length: 0
< Date: Wed, 14 Apr 2010 20:33:32 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0
urn:uuid:53451c5e-1809-4799-8dd8-060672f3e0e1
By inspecting the HTTP Response Location Header one can see the URL to the registered extrinsic. This header is a standard way for exchanging information about a newly created resource using HTTP. The last line of the response is the global unique identifier that the service assigned to the registered extrinsic. The following example details how to publish a new version of the above extrinsic to the service:
% curl -X POST -H "Content-type:application/xml" -v -d @new_product_v2.xml \
http://localhost:8080/registry/extrinsics/logicals/1234
The value of 1234 in the example above represents the logical identifier of the original published extrinsic, which must be specified in order for the service to recognize it as a new version. The following is an example of a extrinsic description in JSON form:
{"description":"This is a new version test product 5678 v1",
"name":"Product 5678 v1",
"objectType":"Product",
"lid":"5678",
"slot":[{"name":"last-name","value":["Doe"]},
{"name":"phone","value":["(818)123-4567","(818)765-4321"]},
{"name":"first-name","value":["Jane"]}]}
The extrinsic description above is contained in the json_product.txt file. The following command registers this extrinsic with the service:
% curl -X POST -H "Content-type:application/json" -v -d @json_product.txt \
http://localhost:8080/registry/extrinsics
In PDS terms, an association is a relationship between two registered artifacts. The following is an example of an association description in XML form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<association xmlns="http://registry.pds.nasa.gov"
sourceObject="1234v1.0"
targetObject="1234v2.0"
associationType="associatedTo"/>
The association description above is contained in the new_association.xml file. The following command registers this association with the service:
% curl -X POST -H "Content-type:application/xml" -v -d @new_association.xml \
http://localhost:8080/registry/associations
In PDS terms, a service is an electronic resource available within the system. A service can be as simple as a web site or as intricate as the Registry Service that is described in this documentation. The following is an example of a service description in XML form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<service xmlns="http://registry.pds.nasa.gov"
name="PDS Service"
description="This is a service to test adding a service description to the registry">
<serviceBinding
name="PDS Main Site"
description="This is the PDS main web site"
accessURI="http://pds.jpl.nasa.gov">
<specificationLink
name="HTTP Specification Link"
description="This is a link to the HTTP specification."
specificationObject="urn:uuid:HTTPSpecificationDocument">
<usageDescription>
Use a browser to access the PDS site. The acceptable browsers are
listed in the usage parameters.
</usageDescription>
<usageParameter>Firefox</usageParameter>
<usageParameter>Safari</usageParameter>
<usageParameter>Internet Explorer</usageParameter>
<usageParameter>Chrome</usageParameter>
</specificationLink>
</serviceBinding>
</service>
The service description above is contained in the new_service.xml file. The following command registers this service with the service:
% curl -X POST -H "Content-type:application/xml" -v -d @new_service.xml \
http://localhost:8080/registry/services
In order for the above artifacts to be accepted for registration by the service, the service must be preloaded with the list of supported object types. This procedure is detailed in the Configuration section of the Installation document. For more information on scheme and node registration see the Scheme and Node Registration document.
Although the Registry Service does not offer an advanced query interface, it does offer interfaces for discovering and retrieving artifact descriptions. The URLs shown in the examples below will work in a web browser.
The following command retrieves a paged list of registered extrinsics (products) from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/extrinsics
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. The following command retrieves the latest extrinsic with logical identifier 1234 from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/extrinsics/logicals/1234
In order to retrieve the earliest extrinsic with logical identifier 1234, append /earliest to the URL in the example above. In order to retrieve the latest extrinsic with logical identifier 1234, append /latest to the URL in the example above. The following command retrieves the specific extrinsic with guid 1234, but in JSON form:
% curl -X GET -H "Accept:application/json" -v \
http://localhost:8080/registry/extrinsics/1234v1.0
The example above will not work in a browser because it is not possible to set the HTTP Accept Header via a browser, but the following command will work in a browser by encoding the return type with a suffix in the URL:
% curl -X GET -v \
http://localhost:8080/registry/extrinsics/1234v1.0.json
The following command retrieves a paged list of registered associations from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/associations
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. In order to retrieve a specific association, append the global unique identifier (/<guid>) for that association to the URL in the example above.
The following command retrieves a paged list of registered services from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/services
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. In order to retrieve a specific service, append the global unique identifier (/<guid>) for that service to the URL in the example above.
The following command retrieves a paged list of registered schemes from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/schemes
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. In order to retrieve a specific scheme, append the global unique identifier (/<guid>) for that scheme to the URL in the example above.
The following command retrieves the list of nodes associated with a specific scheme:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/schemes/<guid>/nodes
In order to retrieve a specific node, append the global unique identifier (/<guid>) for that node to the URL in the example above.
The service tracks auditable events for each registered artifact including submission, approval, deprecation, etc. The following command retrieves a paged list of events from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/events
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. In order to retrieve events for a specific object, append the global unique identifier (/<guid>) for the affected object to the URL in the example above.
When Harvest Tool registers a bundle or collection or products with the service, it precedes the registration with the registration of a package that all of the registered products will be associated with. The following command retrieves a paged list of packages from the service:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/packages
The interface above accepts a number of parameters for filtering the return results. See the API section for a detailed list of the parameters. In order to retrieve a specific package, append the global unique identifier (/<guid>) for that package to the URL in the example above.
When extrinsics are successfully registered with the service they are given a status of Submitted. The status for a specific extrinsic can be modified with the following command:
% curl -X POST -H "Content-type:application/xml" -v \
http://localhost:8080/registry/extrinsics/<guid>/<action>
Valid values for <action> include approve, deprecate and undeprecate. The following diagram details the relationship of the status state with the above actions.
As mentioned above, Harvest Tool associates all registrations with a package. The status for the entire package, including its members, can be modified with the following command:
% curl -X POST -H "Content-type:application/xml" -v \
http://localhost:8080/registry/packages/<guid>/members/<action>
The following command deletes the specific extrinsic from the service:
% curl -X DELETE -v \
http://localhost:8080/registry/extrinsics/<guid>
The same format applies to the other registry objects as well (e.g., associations, services, etc.). As mentioned above, Harvest Tool associates all registrations with a package. An entire package, including its members, can be deleted with the following command:
% curl -X DELETE -v \
http://localhost:8080/registry/packages/<guid>/members
The above command does not delete the package itself. The package can be deleted using the following:
% curl -X DELETE -v \
http://localhost:8080/registry/packages/<guid>
The following command checks to see if the registry service is up and running:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/
The above command will return the list of links to the service's endpoints and an HTTP status of 200. From a web browser, the command returns a welcome message. Make sure to include the trailing slash on the above command.
The following command details the status of the service along with registered counts by Registry Object type:
% curl -X GET -H "Accept:application/xml" -v \
http://localhost:8080/registry/report
A given instance of the Registry Service may be configured to control access to specific URLs utilizing the software of the Security Service or other local mechanism. If this is the case, the curl application can be used to obtain an authentication cookie as follows:
% curl -X GET -H "Accept:application/xml" -v \
https://localhost:8080/registry/ -u username:password -k -c cookie.txt
The cookie file cookie.txt can then be passed to the next curl command:
% curl -X DELETE -v \
https://localhost:8080/registry/extrinsics/<guid> \
-u username:password -k -b cookie.txt
The example above also applies to PUT and POST requests. If HTTPS has not been configured on the local system, use "http" instead of "https" in the commands above.
When the Registry Service instances are deployed to operational environments, the backend databases associated with the services should be backed up periodically with the backup file handled like any other data backup for the organization. The following is a set of instructions for backing up the databases that are dependent on the database server used in the current environment.
For a Derby database instance, execute the following to backup the databases (the path was specified in the Database Configuration section of the Installation document):
% cd /path/to/registrydb/home
% tar czvf registrypds3-<YYYYMMDD>.tar.gz ./registrypds3
% tar czvf registrypds4-<YYYYMMDD>.tar.gz ./registrypds4