Extrinsics

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
        

Associations

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
        

Services

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
        

Schemes and Nodes

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.

Extrinsics

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
        

Associations

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.

Services

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.

Schemes and Nodes

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.

Events

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.

Packages

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.