RESTful CRUD Endpoint

Description

The Catalog REST Endpoint allows clients to perform CRUD operations on the Catalog using REST, a simple architectural style that performs communication using HTTP. The URL exposing the REST functionality is located at http://<HOST>:<PORT>/services/catalog, where HOST is the IP address of where the distirbution is installed and PORT is the port number on which the distribution is listening.

Using the REST CRUD Endpoint

The RESTful CRUD Endpoint provides the capability to query, create, update, and delete metacards in the catalog provider as follows:

Operation	HTTP Request	Details	Example URL
create	HTTP POST	HTTP request body contains the input to be ingested. See InputTransformers for more information.	`http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog`
update	HTTP PUT	The ID of the Metacard to be updated is appended to the end of the URL. The updated metadata is contained in the HTTP body.	`http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/<metacardId>` where <metacardId> is the Metacard.ID of the metacard to be updated
delete	HTTP DELETE	The ID of the Metacard to be deleted is appended to the end of the URL.	`http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/<metacardId>` where <metacardId> is the Metacard.ID of the metacard to be deleted
read	HTTP GET	The ID of the Metacard to be retrieved is appended to the end of the URL. By default, the response body will include the XML representation of the Metacard.	`http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/<metacardId>` where <metacardId> is the Metacard.ID of the metacard to be retrieved
federated read	HTTP GET	The SOURCE ID of a federated source is appended in the URL before the ID of the Metacard to be retrieved is appended to the end.	`http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/sources/<sourceId>/<metacardId>` where <`sourceid>` is the FEDERATED SOURCE ID and <metacardId> is the Metacard.ID of the Metacard to be retrieved

Note that for all RESTful CRUD commands only one metacard ID is supported in the URL, i.e., bulk operations are not supported.

Interacting with the REST CRUD Endpoint

Any web browser can be used to perform a REST read. Various other tools and libraries can be used to perform the other HTTP operations on the REST endpoint (e.g., soapUI, cURL, etc.)

Metacard Transforms with the REST CRUD Endpoint

The read operation can be used to retrieve metadata in different formats.

Install the appropriate feature for the desired transformer. If desired transformer is already installed such as those that come out of the box (xml,html,etc), then skip this step.
Make a read request to the REST URL specifying the catalog id.

Add a transform query parameter to the end of the URL specifying the shortname of the transformer to be used (e.g., transform=kml).
Example:

http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/<metacardId>?transform=<TRANSFORMER_ID>

Transforms also work on read operations for metacards in federated sources.

http://<DISTRIBUTION_HOST>:<DISTRIBUTION_PORT>/services/catalog/sources/<sourceId>/<metacardId>?transform=<TRANSFORMER_ID>

Metacard Transforms Available in DDF

Unable to render {children}. Page not found: DDF:Included Metacard Transformers.

MetacardTransformers can be added to the system at any time. This endpoint can make use of any registered MetacardTransformers.

InputTransformers

This REST Endpoint uses InputTransformers to create metacards from a create or a HTTP POST operation. The REST Endpoint dynamically finds InputTransformers that support the Content-Type stated in the HTTP header of a HTTP POST. InputTransformers register as Services with a list of mime-types. The REST Endpoint receives a list of InputTransformers that match the Content-Type and one-by-one calls the InputTransformers until a transformer is successful and creates a Metacard. For instance, if GeoJSON was in the body of the HTTP POST, then the HTTP Content-Type header would need to include application/json in order to match the mime-type GeoJSON Input Transformer supports.

The following are the included InputTransformers:

Tika Input Transformer — transforms a Microsoft Office, PDF, and OpenOffice documents into a Catalog Metacard
GeoJSON Input Transformer — transforms GeoJSON into a Catalog Metacard

InputTransformers can be added to the system at any time.

Installation and Uninstallation

The RESTful CRUD Endpoint can be installed and uninstalled using the normal processes described in the Configuration section.

Configuration

The RESTful CRUD Endpoint has no configurable properties. It can only be installed or uninstalled.

Implementation Details

Imported Services

Registered Interface	Availability	Multiple
`ddf.mime.MimeTypeToTransformerMapper`	required	false
`ddf.catalog.CatalogFramework`	required	false
`ddf.catalog.filter.FilterBuilder`	required	false

Exported Services

Registered Interface	Service Property	Value
`ddf.action.ActionProvider`	id	catalog.data.metacard.view
`ddf.catalog.util.DdfConfigurationWatcher`

Known Issues

None