️Command Line API

This section contains details on the interfaces for the command line tools.

pds-doi-cmd

PDS core command for DOI management. The available subcommands are: reserve (Submit a request to reserve a DOI prior to public release. Reserved DOI’s may be released after via the release action), update (Update a record with or without submission to the service provider. Metadata updates are pulled from the provided input file for the corresponding DOI values.), release (Move a reserved DOI to review, or submit a DOI for release to the service provider), check (Check for pending DOI submissions from the service provider and update the local database with any changes in status), list (List DOI entries within the transaction database that match the provided search criteria),

usage: pds-doi-cmd [-h] {reserve,update,release,check,list} ...

Positional Arguments

subcommand: Possible choices: reserve, update, release, check, list

Sub-commands:

reserve

Reserve DOI’s for one or more unpublished datasets. DOI’s will be assigned by the provider, but will not be publicly findable. To create findable records, utilize the Release action with the labels returned by this action.

pds-doi-cmd reserve [-h] -i INPUT -N NODE_ID [-s EMAIL] [-f]

options

-i, --input

Path to a PDS4 XML label or XLS/CSV spreadsheet file with the following columns: title,publication_date,product_type_specific,author_last_name,author_first_name,related_resource

-N, --node

The PDS Discipline Node in charge of the submission of the DOI(s). Authorized values are: atm,eng,geo,img,naif,ppi,rs,rms,sbn,unk

-s, --submitter

The email address to associate with the Reserve request. Defaults to pds-operator@jpl.nasa.gov

Default: “pds-operator@jpl.nasa.gov”

-f, --force

If provided, forces the reserve action to proceed even if warnings are encountered during submission of the Reserve request. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

update

Update records with DOI’s already assigned

pds-doi-cmd update [-h] -i INPUT [-N NODE_ID] [-s EMAIL] [-f]

options

-i, --input

Path to an input XML/JSON label or CSV/XLS spreadsheet. May be a local path or an HTTP address resolving to a PDS4 label file. Each record parsed from the input MUST define a DOI value in order to be updated.

-N, --node

The PDS Discipline Node to assign to each updated record. If not provided,the node(s) currently assigned to each record are maintained. Authorized values are: atm,eng,geo,img,naif,ppi,rs,rms,sbn,unk

-s, --submitter

The email address to associate with the Update request. Defaults to pds-operator@jpl.nasa.gov

Default: “pds-operator@jpl.nasa.gov”

-f, --force

If provided, forces the action to proceed even if warnings are encountered during submission of the updated record to the database. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

release

Release a DOI, in draft or reserve status, for review. A DOI may also be released to the DOI service provider directly.

pds-doi-cmd release [-h] -i INPUT [-N NODE_ID] [-s EMAIL] [-f] [--no-review]

options

-i, --input

Path to a file containing the record to release. The format may be either a PDS4 label, or a DataCite JSON label. DataCite JSON labels are produced by the Reserve and Draft actions, and can be retrieved for a DOI with the List action.

-N, --node

The PDS Discipline Node in charge of the released DOI. If not provided,the node(s) currently assigned to each record are maintained.Authorized values are: atm,eng,geo,img,naif,ppi,rs,rms,sbn,unk

-s, --submitter

The email address to associate with the Release request. Defaults to pds-operator@jpl.nasa.gov

Default: “pds-operator@jpl.nasa.gov”

-f, --force

If provided, forces the release action to proceed even if warning are encountered during submission of the release request. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

--no-review

If provided, the requested DOI will be released directly to the DOI service provider for registration. Use to override the default behavior of releasing a DOI to “Review” status.

Default: True

check

Check the status of all pending DOI submissions.

pds-doi-cmd check [-h] [-e] [-a] [-s EMAIL]

options

-e, --email

If provided, the check action sends results to the default recipients and pending DOI submitters.

Default: False

-a, --attachment

If provided, the check action sends results as an email attachment. Has no effect if –email is not also provided.

Default: False

-s, --submitter

The email address of the user to register as author of the check action.

list

Extracts the submitted DOI from the local transaction database using the following selection criteria. Output is returned in JSON format.

pds-doi-cmd list [-h] [-f {record,label}] [-N NODE_ID[,NODE_ID]...]
                 [-status STATUS[,STATUS]...] [-doi DOI[,DOI]...]
                 [-i ID[,ID]...] [-start YYYY-MM-DD[THH:mm:ss.ssssss[Z]]]
                 [-end YYYY-MM-DD[THH:mm:ss.ssssss[Z]]] [-s EMAIL]

options

-f, --format

Possible choices: record, label

Specify the format of the results returned by the list query. Valid options are “record” for a list of transaction records, or “label” for an output JSON label containing entries for all DOI records that match the query. Defaults to “record”.

Default: “record”

-N, --node

A list of comma-separated node names to filter the available DOI entries by. Valid values are: atm,eng,geo,img,naif,ppi,rs,rms,sbn,unk

-status, --status

A list of comma-separated submission status values to filter the database query results by. Valid status values are: error, unknown, reserved, draft, review, pending, registered, findable, deactivated

-doi, --doi

A list of comma-delimited DOI values to use as filters with the database query. Each DOI may contain one or more wildcards (*) to pattern match against.

-i, --ids

A list of comma-delimited PDS identifiers to use as filters with the database query. Each ID may contain one or more wildcards (*) to pattern match against.

-start, --start-update

The start time of the record update to use as a filter with the database query. Should conform to a valid isoformat date string. By default, the local time zone is assumed. To provide a time in UTC, append a ‘Z’ to the time portion of the provided date-time.

-end, --end-update

The end time for record update time to use as a filter with the database query. Should conform to a valid isoformat date string. By default, the local time zone is assumed. To provide a time in UTC, append a ‘Z’ to the time portion of the provided date-time.

-s, --submitter

A list of comma-separated email addresses to use as a filter with the database query. Only entries containing the one of the provided addresses as the submitter will be returned.

Usage for each subcommand is available by providing the –help argument to the subcommand:: pds-doi-cmd reserve –help

pds-doi-init

Script to bulk import existing DOIs into the local transaction database.

usage: pds-doi-init [-h] [-S SERVICE] [-p PREFIX] [-s SUBMITTER_EMAIL]
                    [-d DB_NAME] [-i INPUT_FILE] [-o OUTPUT_FILE] [--dry-run]
                    [--debug]

options

-S, --service

Name of the service provider to pull existing DOI records from. If not provided, the provider configured by the DOI service configuration INI is used by default. Should be one of: [osti, datacite]

-p, --prefix

Specify the DOI prefix value to query the service provider for. If not provided, the prefix value configured to the providing in the INI config is used by default.

-s, --submitter-email

The email address of the user performing the deployment database initialization. Defaults to pds-operator@jpl.nasa.gov.

Default: “pds-operator@jpl.nasa.gov”

-d, --db-name

Name of the SQLite3 database file name to commit DOI records to. If not provided, the file name is obtained from the DOI service INI config.

-i, --input-file

Input file (XML or JSON) to import existing DOIs from. If no value is provided, the server URL specified by the DOI service configuration INI file is used by default.

-o, --output-file

Path to write out the DOI JSON labels as returned from the query. When created, this file can be used with the –input option to import records at a later time without re-querying the server. This option has no effect if –input already specifies an input file.

--dry-run

Flag to suppress actual writing of DOIs to database.

Default: False

--debug

Flag to print debug statements.

Default: False

Note: When DOI records are imported to the local transaction database, the DOI service creates an associated output label for each record under the transaction_history directory. The format of this output label is driven by the SERVICE.provider field of the INI. Please ensure the field is set appropriately before using this script, as a mismatch could cause parsing errors when using the DOI service after this script.

Swagger API

This section contains details Swagger REST API implemented by pds-doi-api.

Planetary Data System DOI Service API

PDS API for managing DOI registration with a DOI service provider (OSTI, DataCite, etc.).

More information: https://github.com/NASA-PDS/doi-service

Contact Info: pds-operator@jpl.nasa.gov

Version: 0.2

BasePath:/PDS_APIs/pds_doi_api/0.2

http://apache.org/licenses/LICENSE-2.0.html

Access

Methods

[ Jump to Models ]

Dois

Up

get /dois/check

(getCheckDois)

Check submission status of all records pending release.

Query parameters

email (optional)

Query Parameter — If true, the check action sends results to the default recipients and pending DOI submitters. default: false

attachment (optional)

Query Parameter — If true, the check action sends results as an email attachment. Has no effect if the email flag is not set to true. default: false

submitter (required)

Query Parameter — The email address of the user to register as author of the check action. This address is also included in the list of recipients.

Return type

doi_record

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Success doi_record

400

DOI service provider cannot be reached

500

Internal error

Up

get /doi

(getDoiFromId)

Get the status of a DOI from the transaction database.

Query parameters

identifier (required)

Query Parameter — The PDS identifier associated with the record to fetch.

Return type

doi_record

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Success doi_record

Example data

Content-Type: application/json

[
    {
        "creation_date":"2021-03-09T00:00:00Z",
        "doi":"10.17189/29476",
        "identifier":"urn:nasa:pds:lab_shocked_feldspars::1.0",
        "node":"eng",
        "record":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<records>\n
            <record status=\"reserved\">\n        <id>29476</id>\n
            <title>Laboratory Shocked Feldspars Bundle</title>\n
            <doi>10.17189/29476</doi>\n        ...\n
            <contact_name>PDS Operator</contact_name>\n
            <contact_org>PDS</contact_org>\n
            <contact_email>pds-operator@jpl.nasa.gov</contact_email>\n
            <contact_phone>818.393.7165</contact_phone>\n
            </record>\n</records>\n",
        "status":"reserved",
        "submitter":"my.email@node.gov"
    }
]

404

Not existing

500

Internal error

Up

get /dois

(getDois)

List the DOI requests within the transaction database

Query parameters

doi (optional)

Query Parameter — List of DOIs to fetch from transaction database.

submitter (optional)

Query Parameter — List of submitter email addresses to filter DOIs by.

node (optional)

Query Parameter — List of PDS node names cited as contributor of the DOI to filter by. Each identifier must be one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146

status (optional)

Query Parameter — List of DOI workflow status values to filter results by. Status must be one of the following - "unknown", "draft", "review", or "findable".

ids (optional)

Query Parameter — List of PDS identifiers to filter DOIs by. Each identifier may contain one or more Unix-style wildcards (*) to pattern match against.

start_date (optional)

Query Parameter — A start date to filter resulting DOI records by. Only records with an update time after this date will be returned. Value must be a valid isoformat string of the form <YYYY>-<mm>-<dd>[T<HH>:<MM>:<SS>.<ms>]

end_date (optional)

Query Parameter — An end date to filter resulting DOI records by. Only records with an update time prior to this date will be returned. Value must be a valid isoformat string of the form <YYYY>-<mm>-<dd>[T<HH>:<SS>.<ms>]

Return type

array[doi_summary]

Example data

Content-Type: application/json

[
    {
        "identifier" : "identifier",
        "node" : "node",
        "submitter" : "submitter",
        "title" : "title",
        "update_date" : "2000-01-23T04:56:07.000+00:00",
        "doi" : "doi",
        "status" : "status"
    },
    {
        "identifier" : "identifier",
        "node" : "node",
        "submitter" : "submitter",
        "title" : "title",
        "update_date" : "2000-01-23T04:56:07.000+00:00",
        "doi" : "doi",
        "status" : "status"
    }
]

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Success

400

Invalid Argument

500

Internal error

Up

post /dois

(postDois)

Submit a DOI to reserve or update. The payload includes URLs for one or more records to be submitted. Record URLs must resolve to PDS4 label files (xml).

Consumes

This API call consumes the following media types via the request header:

application/json
application/xml

Request body

body labels_payload (optional)

Body Parameter — Payload containing one or more labels in JSON or XML (PDS4) format. Required for reserve requests, but optional for update.

example:

{
  "labels" : [ {
    "status" : "Reserved",
    "title" : "Laboratory Shocked Feldspars Bundle",
    "publication_date" : "2020-03-11",
    "product_type_specific" : "PDS4 Collection",
    "author_last_name" : "Johnson",
    "author_first_name" : "J. R.",
    "related_resource" : "urn:nasa:pds:lab_shocked_feldspars"
  } ]
}

Query parameters

action (required)

Query Parameter — The submission action to perform. Must be one of "reserve", "draft" or "update". "draft" is an alias for "update".

submitter (required)

Query Parameter — Email address of the submission requester.

node (required)

Query Parameter — The PDS node name to cite as contributor of the DOI. Must be one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146

url (optional)

Query Parameter — URL to provide as the record to register a DOI for. URL must start with either "http://" or "https://" and resolve to a valid PDS4 label in XML format. This value is only utilized when request is set to "update".

force (optional)

Query Parameter — If true, forces a reserve request to completion, ignoring any warnings encountered. Has no effect for update requests. default: false

Return type

doi_record

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Success doi_record

Example data

Content-Type: application/json

[
    {
        "creation_date":"2021-03-09T00:00:00Z",
        "doi":"10.17189/29476",
        "identifier":"urn:nasa:pds:lab_shocked_feldspars::1.0",
        "node":"eng",
        "record":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n
            <records>\n    <record status=\"reserved\">\n
            <id>29476</id>\n        <title>Laboratory Shocked Feldspars Bundle</title>\n
            <doi>10.17189/29476</doi>\n        ...\n
            <contact_name>PDS Operator</contact_name>\n
            <contact_org>PDS</contact_org>\n
            <contact_email>pds-operator@jpl.nasa.gov</contact_email>\n
            <contact_phone>818.393.7165</contact_phone>\n
            </record>\n</records>\n",
        "status":"reserved",
        "submitter":"my.email@node.gov"
     }
]

201

Success

400

Invalid Argument

500

Internal error

Up

post /doi/submit

(postSubmitDoi)

Move a DOI record from draft status to "review".

Query parameters

identifier (required)

Query Parameter — The PDS identifier associated with the record to submit for review.

force (optional)

Query Parameter — If true, forces a submit request to completion, ignoring any warnings encountered. default: false

Return type

doi_record

Example data

Content-Type: application/json

""

Produces

This API call produces the following media types according to the request header; the media type will be conveyed by the response header.

application/json

Responses

200

Success doi_record

400

Can not be released

404

No entry found for identifier

500

Internal error

Up

put /doi

(putDoiFromId)

Update the record associated with an existing DOI.

Query parameters

identifier (required)

Query Parameter — The PDS identifier associated with the record to fetch.

submitter (optional)

Query Parameter — Email address of the DOI update requester.

node (optional)

Query Parameter — The PDS node name to cite as contributor of the DOI. Must be one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146

url (optional)

Query Parameter — URL to provide as the record to update the DOI with. URL must start with either "http://" or "https://" and resolve to a valid PDS4 label in XML format.