RESTful CRUD Endpoint
- Shaun Morris
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. |
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. |
|
| 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. |
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. |
where < |
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
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