Skip to content

Latest commit

 

History

History
198 lines (165 loc) · 5.13 KB

exampleusage.md

File metadata and controls

198 lines (165 loc) · 5.13 KB

Example Usage

The usage of the Policy API is strictly a read-only interface. The command line usage of the system provides tools to update data in the metadata API and are mostly cronjob like processes.

The API

The policy server is split up into endpoints named for their Pacifica project that utilizes them. So the path /uploader is used by the Pacifica Uploader (http://github.com/pacifica/pacifica-uploader) to control its behavior. The idea is that workflow implemented by the various Pacifica projects has some element of site or instance specific policy that can be applied to the running service. The policy is driven by the metadata and thus this project should talk to the metadata service.

Events API

The Events API is used by the Notifications service. The role of this query is to verify the event recieved by the Notifications services is allowed to be sent to the user on the URL path.

Request Example:

POST /events/dmlb2001
Content-Type: application/json
{
  "data": [
    ...
  ]
}

Good Response Example:

Http-Code: 200
{
  "status": "success"
}

Failed Response Example:

Http-Code: 401
{
  "error": "..."
}

The underlying logic for this implementation is the same as the ingest endpoint discussed next.

Ingest API

The Ingest API is used by the Ingest service. This endpoint verifies the relationships between user, project and instrument before allowing an upload. The content of the body document is defined by the uploader.

Request Example:

POST /ingest
Content-Type: application/json
[
  ...
]

Good Response Example:

Http-Code: 200
{
  "status": "success"
}

Failed Response Example:

Http-Code: 401
{
  "error": "..."
}

Reporting and Status API

This document is not going into details about these APIs currently. These endpoints are supposed to be used by tools that provide status of current uploads to users of Pacifica as well as institutional reporting tools that aggregate metrics about uploads in Pacifica. Eventually, Pacifica should have a basic set of these websites to allow users to use these endpoints but not currently.

Uploader API

The Uploader API is a simple query interface to get complex metadata interactively while users are using the Uploader. This API has a JSON document that looks very SQL like but is not complete.

Request Example:

POST /uploader
Content-Type: application/json
{
  "user": 100,
  "from": "instruments",
  "columns": [
    "_id",
    "name"
  ],
  "where": {
    "_id": 54
  }
}

Good Response Example:

Http-Code: 200
[
  {
    "_id": 54,
    "name": "NMR PROBES: Nittany Liquid"
  }
]

Failed Response Example:

Http-Code: 500

Admin Command Line

There is a single admin command line tool (pacifica-policy-cmd) with two subcommands, data_release and searchsync. The data_release subcommand handles setting the data_release attributes of the Projects and Transactions. The searchsync subcommand handles formatting and synchonizing metadata to ElasticSearch.

$ pacifica-policy-cmd --help
usage: pacifica-policy-cmd [-h] [--verbose] {data_release,searchsync} ...

positional arguments:
  {data_release,searchsync}
                        sub-command help
    data_release        data_release help
    searchsync          searchsync help

optional arguments:
  -h, --help            show this help message and exit
  --verbose             enable verbose debug output

Data Release

The data release process involves two phases, updating the suspense date and setting data release. The suspense date is a date that the metadata and data associated with that object in metadata will be released in the future. The data release phase checks the suspense date with now to determine if the object needs to have it released.

$ pacifica-policy-cmd data_release --help
usage: pacifica-policy-cmd data_release [-h]
                                        [--exclude [EXCLUDE [EXCLUDE ...]]]
                                        [--keyword KEYWORD]
                                        [--time-after TIME_AFTER]
                                        [--time-ago TIME_AGO]

data release by policy

optional arguments:
  -h, --help            show this help message and exit
  --exclude [EXCLUDE [EXCLUDE ...]]
                        id of keyword prefix to exclude.
  --keyword KEYWORD     keyword one of projects.actual_end_date,
                        projects.actual_start_date, projects.submitted_date,
                        projects.accepted_date, projects.closed_date,
                        transactions.created, transactions.updated.
  --time-after TIME_AFTER
                        set suspense date on data to X days after keyword.
  --time-ago TIME_AGO   only objects updated after X days ago.

Example command lines from the test suite.

pacifica-search-cmd data_release --time-after='365 days after' --exclude='1234cé'
pacifica-search-cmd data_release --keyword='transactions.created' --verbose