"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

PID Service Application Programming Interface (API)

Contents

User Guide

Overview

The PID Service provides an Application Programming Interface (API) for remote management of URI mapping rules. The service exposes a single endpoint that allows programmatic interaction with the service via HTTP protocol. controller endpoint accepts GET and POST requests depending on the operation type. The API endpoint would normally be hidden behind a firewall to restrict unauthorized access or may require additional step to be taken to perform remote authentication.

Further in this guide, unless explicitly stated, all commands are invoked through the controller HTTP handler.

All commands are initiated by cmd GET parameter that is required for all requests. See details for all supported commands below.

Example:
http://localhost/pidsvc/controller?cmd=%COMMAND_TYPE%

On successful completion all commands should return an HTTP 200 response code with a command-specific response body.

URI Mappings

Create URI Mapping

Create a new URI mapping. Note that previously created and active URI mappings for the same URI mapping string are getting automatically tomb-stones, i.e. superseded by the new ones.

HTTP method POST
cmd create_mapping
POST body accepts XML-serialized definition of the URI mapping that conforms to mapping.xsd XML Schema. See https://www.seegrid.csiro.au/subversion/PID/trunk/pidsvc/src/main/resources/csiro/pidsvc/mappingstore/xsd/mapping.xsd.

POST body XML-serialized definition of the URI mapping.

Delete URI Mapping

Delete URI mappings in the data store. Note that URI mappings in the database aren't physically deleted and remain in the database marked as 'tomb-stones' entities.

HTTP method POST
cmd delete_mapping
Additional HTTP POST parameters:

mapping_path URI-encoded URI mapping string (i.e. URI or regular expression)

Merge URI Mappings

Merge two mapping rules. See details of the merge operation in the user guide.

HTTP method GET
cmd merge
mapping_path URI-encoded URI mapping string of the target rule. Mandatory.
replace Boolean flag (0 or 1) that indicates whether or not the service will replace fully matching conditions (by type and definition) instead of appending new ones. This option will also eliminate fully matching conditions. By default, new conditions from uploaded configuration file will be appended to the bottom of the list of conditions.
POST body must contain the source mapping in XML-based configuration format and must be conformant with https://www.seegrid.csiro.au/subversion/PID/trunk/pidsvc/src/main/resources/csiro/pidsvc/mappingstore/xsd/mapping.xsd or https://www.seegrid.csiro.au/subversion/PID/trunk/pidsvc/src/main/resources/csiro/pidsvc/mappingstore/xsd/backup.xsd and must contain a single mapping rule with one or more conditions.

See a remote procedure call example in the attached Fiddler session:

Upon completion the service will return a simple JSON response with the status of operation.

Partial/Full URI Mapping Export

Export a URI mapping in a *.psb file format (PID Service Backup - binary file format) or *.xml (PID Service Backup - XML based file format) . Partial export contains only the latest URI mapping configuration whereas the full export generates a file that also preserves the change history for the URI mapping.

HTTP method GET
cmd partial_export or full_export
Additional HTTP GET parameters:

mapping_id Numeric identifier of the mapping to be exported.
mapping_path URI mapping to be exported.
If both mapping_id and mapping_path are present, then mapping_id parameter will take precedence.

Returns: PID Service Backup in a binary *.psb file.

Partial/Full Data Store Backup

Backup the whole data store in a *.psb file format (PID Service Backup). Partial backup contains only the latest URI mapping configurations whereas the full back generates a file that also preserves the change history for URI mappings.

HTTP method GET
cmd partial_backup or full_backup
Additional HTTP GET parameters:

deprecated Boolean flag (true or false) that indicates whether deprecated mapping should be included in the backup or not.
lookup Boolean flag (true or false) that indicates whether lookup map configurations should be included in the backup or not. Default is true.

Returns: PID Service Backup in a binary *.psb file.

Import URI Mappings

Import partial or full backups.

HTTP method POST
cmd import
This command accepts a POST requests using multipart/mixed encoding type, as specified by RFC 1867 with a single file attachment in *.psb format (PID Service Backup - binary file format) or *.xml (PID Service Backup - XML based file format).

POST body PID Service Backup in either *.psb or *.xml format.
POST body accepts either PID Service Binary Backup or XML-serialized definition of the URI mappings that conforms to backup.xsd XML Schema.

Note that backup.xsd XML schema allows to combine URI mapping and lookup map configurations in the same file.

For more documentation refer to Batch Import section of the User Guide.

Purge Data Store

Purge the data store content.

HTTP method POST
cmd purge_data_store

POST body n/a

Condition Sets

Create

Create a new condition set. Note that previously created condition set with the same name will be automatically superseded by the new one.

HTTP method POST
cmd create_condition_set
POST body accepts XML-serialized definition of the condition set that conforms to conditionSet.xsd XML Schema. See https://www.seegrid.csiro.au/subversion/PID/trunk/pidsvc/src/main/resources/csiro/pidsvc/mappingstore/xsd/conditionSet.xsd.

POST body XML-serialized definition of the condition set.

Delete

Delete condition set from the data store.

HTTP method POST
cmd delete_condition_set
Additional HTTP POST parameters:

name Name of the condition set to be exported.

Export

Export a condition set in a *.psb file format (PID Service Backup - binary file format) or *.xml (PID Service Backup - XML based file format).

HTTP method GET
cmd export_condition_set
Additional HTTP GET parameters:

name Name of the condition set to be exported.
format Export file format (psb or xml).

Returns: PID Service Backup in a binary (*.psb) or XML (*.xml) file.

Import

To import a condition set into the data store use the import web method. See Import URI Mappings.

Lookup Maps

Create

Create a new lookup map. Note that previously created lookup map for the same namespace will be automatically superseded by the new one.

HTTP method POST
cmd create_lookup
POST body accepts XML-serialized definition of the lookup map that conforms to lookup.xsd XML Schema. See https://www.seegrid.csiro.au/subversion/PID/trunk/pidsvc/src/main/resources/csiro/pidsvc/mappingstore/xsd/lookup.xsd.

POST body XML-serialized definition of the lookup map.

Get lookup map

Retrieve details of a lookup map by namespace.

Please note that this web method is using info HTTP handler (not the controller handler) and a GET HTTP method.

Handler info (e.g., http://hostname/pidsvc/info?cmd=get_lookup_config)
HTTP method POST
cmd get_lookup_config

Additional HTTP GET parameters:

ns URI-encoded namespace of the lookup map to be retrieved.

Delete

Delete lookup map from the data store.

HTTP method POST
cmd delete_lookup
Additional HTTP POST parameters:

ns URI-encoded namespace of the lookup map to be deleted.

Export

Export a lookup in a *.psl file format (PID Service Lookup Map Backup - binary file format) or *.xml (PID Service Backup - XML based file format).

HTTP method GET
cmd export_lookup
Additional HTTP GET parameters:

ns Namespace of the lookup map to be exported.
format Export file format (psl or xml).

Returns: PID Service Lookup Map Backup in a binary (*.psl) or XML (*.xml) file.

Import

Import lookup map backup.

HTTP method POST
cmd import_lookup
This command accepts a POST requests using multipart/mixed encoding type, as specified by RFC 1867 with a single file attachment in *.psl format (PID Service Lookup Map Backup - binary file format) or *.xml (PID Service Lookup Map Backup - XML based file format).

POST body PID Service Backup in either *.psl or *.xml format.
POST body accepts either PID Service Binary Lookup Map Backup or XML-serialized definition of the lookup map that conforms to lookup.xsd XML Schema.

-- PavelGolodoniuc - 22 Oct 2012
Topic attachments
I Attachment Action Size Date Who Comment
merge.sazsaz merge.saz manage 3.1 K 18 Oct 2013 - 16:42 PavelGolodoniuc merge command test
Topic revision: r8 - 02 Sep 2016, PavelGolodoniuc
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).