Caltech Library logo

NAME

ep3apid

SYNOPSIS

ep3apid OPTIONS [SETTINGS_FILENAME]

DESCRIPTION

Run an extended EPrints 3.x web API based on direct manipulation of EPrint’s MySQL database(s).

DETAIL

ep3apid can be run from the command line and the will create an http web service. The web service provides a limitted number of end points providing eprint ids for content matched in EPrints’s MySQL databases. You can configure it to provide read/write support to and from the MySQL databases used by EPrints.

The following URL end points are intended to take one unique identifier and map that to one or more EPrint IDs. This can be done because each unique ID targeted can be identified by querying a single table in EPrints. In addition the scan can return the complete results since all EPrint IDs are integers and returning all EPrint IDs in any of our repositories is sufficiently small to be returned in a single HTTP request.

Configuration information

There are two end points that give you information about what repositories are configured in for ep3apid and what the database structure (tables and column names) for each configure repository.

Unique ID to EPrint ID

Unique ids maybe standards based (e.g. ORCID, DOI, ISSN, ISBN) or internal (e.g. group ids, funder ids)

Change Events

The follow API end points would facilitate faster updates to our feeds platform as well as allow us to create a separate public view of our EPrint repository content.

Read/Write API

As of ep3apid version 1.0.3 a new set of end points exists for reading (retreiving EPrints XML) and writing (metadata import) of EPrints XML. The extended API only supports working with EPrints metadata not directly with the documents or files associated with individual records.

The metadata import functionality is enabled per repository. It only supports importing records at this time. Importing an EPrint XML document, which could containing multiple EPrint metadata records, is implemented purely using SQL statements and not the EPrints Perl API. This allows you (with the right MySQL configuration) to run the extended API on a different server without resorting to Perl.

settings.json (configuration)

The JSON settings.json file should look something like “REPO_ID” would be the name used in the ep3apid to access a specific repsitory. The “dsn” value should be replaced with an appropriate data source name to access the MySQL database for the repository you’re supporting. You can have many repositories configured in a single ep3apid instance.

    {
        "repositories": {
            "REPO_ID": {
                "dsn": "DB_USER:SECRET@/DB_NAME",
                "base_url": "URL_TO_EPRINT_REPOSITORY",
                "write": false,
                "default_collection": "REPO_ID",
                "default_official_url": "PERMA_LINK_URL",
                "default_rights": "RIGHTS_STATEMENT_GOES_HERE",
                "default_refereed": "TRUE",
                "default_status": "inbox"
            },
            ... /* Additional repositories configured here */ ...
        }
    }

NOTE: The “default_collection”, “default_official_url”, “default_rights”, “default_refereed”, “default_status” are option configurations in the ‘settings.json’ file.

OPTIONS

-help
Display this help message
-license
Display software license
-version
Display software version

EXAMPLES

To run the web service create a JSON file named settings.ini in the current directory where you’re invoking ep3apid from. The web service can be started with running

    ep3apid

or to load “settings.json” from the current work directory.

    ep3apid settings.json

ep3apid 1.2.4