Table of contents

DOIDB API

Architecture

The DOIDB is implemented as a proxy to the DataCite Metadata Store. The process of minting a DOI or the deposition of metadata triggers a live registration at DataCite. Additionaly DOIDB keeps track of used DOIs, stores the metadata and offers a local OAI-PMH service and a search service.

This API is intended to be used in programs and you will need a valid login. The account data is the same as for the web interface of http://doidb.wdc-terra.org/mds.

Overview

The API is implemented in REST style. The end point you are going to use is:

https://doidb.wdc-terra.org/mds

At the moment there are two resources:

/doi

/metadata

/media

/difmetadata

/isometadata

The URI https://doidb.wdc-terra.org/mds/doi accepts requests with POST HTTP method.

The URI https://doidb.wdc-terra.org/mds/doi/{doi}, where {doi} is a actually DOI, accepts requests with GET HTTP method.

The URI https://doidb.wdc-terra.org/mds/metadata accepts requests with POST HTTP method.

The URI https://doidb.wdc-terra.org/mds/metadata/{doi}, where {doi} is an actual DOI, accepts requests with 3 HTTP methods: POST, GET, and DELETE

The URI https://doidb.wdc-terra.org/mds/difmetadata/{doi}, where {doi} is an actual DOI, accepts requests with 3 HTTP methods: POST, GET, and DELETE

The URI https://doidb.wdc-terra.org/mds/isometadata/{doi}, where {doi} is an actual DOI, accepts requests with 3 HTTP methods: POST, GET, and DELETE

The URI https://mds.datacite.org/media/{doi}, where {doi} is an actual DOI, accepts requests with 2 HTTP methods: GET and POST

In addition HEAD is allowed, whenever GET is.

Characters

DataCite recommends that only the following characters are used within a DOI name:

  • 0-9
  • a-z
  • A-Z
  • - (dash)
  • . (dot)
  • _ (underscore)
  • + (plus)
  • : (colon)
  • / (slash)

Security and Accounts

All the traffic goes via HTTPS. All requests to this system are password protected and require HTTP Basic authentication header.

Accounts have some constraints associated:

  • you will be allowed to mint DOIs only with prefix assigned to you
  • you will be allowed to mint DOIs only with URLs in host domains assigned to you
  • the number of DOIs available for registration can be limited.

Handle System

It is important to understand that the Handle System (the technical infrastructure for DOIs) is a distributed network system. The consequence of this manifests is its inherent latency. For example, DOIs have TTL (time to live) defaulted to 24 hours, so your changes will be visible to the resolution infrastructure only when the TTL expires. Also, if you create a DOI and then immediately try to update its URL, you might get the error message HANDLE NOT EXISTS. This is because it takes some time for the system to register a handle for a DOI.

Metadata

DOIDB accepts three different metadata schemata - DataCite, DIF 9.8.2, and ISO19139. It is possible to generate DataCite metadata through stylesheet transformation by extracting the relevant information from the DIF or ISO schema. Metadata are validated to conform to their specific schema. ISO-metadata is (preferably) INSPIRE conform and validates the validator of the EU. To get an idea how your metadata could look like, please browse the OAI-PMH repository
  • DataCite must conform to the standards published by DataCite at Metadata Schema Repository. You will find there the preferred version and exmaple XML document. The schema is primarily used to allow cross-linking of datasets and publications using persistent identifiers.
  • NASA DIF metadata is supported in version DIF 9.8.2 and can be stored independet from the DataCite metadata. However, if you want to use the automatic conversion into the DataCite schema, some fields are required and should look as follows:
    • Data_Set_Citation/Dataset_Creator a semicolon separated list of authors Lastname1, Firstname1; Lastname2, Firstname2; Lastname3, Firstname3
    • Data_Set_Citation/Dataset_Title the dataset title
    • Data_Set_Citation/Dataset_Release_Date as YYYY-MM-DD
    • Data_Set_Citation/Dataset_Publisher should be Deutsches GeoForschungsZentrum GFZ
  • ISO19139 metadata is supported and can be stored independet from the DataCite metadata. However, if you want to use the automatic conversion into the DataCite schema, some fields are required and should look as follows:
    • authors
      • are below identificationInfo/MD_DataIdentification/citation/CI_Citation/citedResponsibleParty/CI_ResponsibleParty/individualName/CharacterString
      • with role author identificationInfo/MD_DataIdentification/citation/CI_Citation/citedResponsibleParty/CI_ResponsibleParty/role/CI_RoleCode
    • publication year
      • is derived from identificationInfo/MD_DataIdentification/citation/CI_Citation/date/CI_Date/date/Date
      • with datetype publication identificationInfo/MD_DataIdentification/citation/CI_Citation/date/CI_Date/dateType/CI_DateTypeCode
    • publisher
      • is derived from identificationInfo/MD_DataIdentification/citation/CI_Citation/citedResponsibleParty/CI_ResponsibleParty/organisationName/CharacterString
      • with role publisher identificationInfo/MD_DataIdentification/citation/CI_Citation/citedResponsibleParty/CI_ResponsibleParty/role/CI_RoleCode
    • keywords
      • are derived from identificationInfo/MD_DataIdentification/descriptiveKeywords/MD_Keywords/keyword/CharacterString
    • title
      • is derived from identificationInfo/MD_DataIdentification/citation/CI_Citation/title
    • abstract
      • is derived from identificationInfo/MD_DataIdentification/abstract/CharacterString

Testing

Each API call can have optional query parametertestMode. If set to "true" or "1" the request will not change the database nor will the DOI handle will be registered or updated, e.g. POST /doi?testMode=true.

Also please note that there is special test prefix 10.5072 available to all datacentres. Please use it for all your testing DOIs. Your real prefix should not be used for test DOIs. Note that DOIs with test prefix will behave like any other DOI, e.g. they can be normally resolved. They will not be exposed by upcoming services like search and OAI, though. Periodically we purge all 10.5072 datasets from the system.

Code examples

We have a number of code examples - please see Github.

API reference

Doi API

GET

URI: https://doidb.wdc-terra.org/mds/doi/{doi} where {doi} is a specific DOI.

This request returns an URL associated with a given DOI.

Request headers

none

Request body

empty

Response headers

none

Response body

If response status is 200: URL representing a dataset; empty for 204; otherwise short explanation for non-200 status

Response statuses

200 OK - operation successful

204 No Content - DOI is known to MDS, but is not minted (or not resolvable e.g. due to handle's latency)

401 Unauthorized - no login

403 - login problem or dataset belongs to another party

404 Not Found - DOI does not exist in our database

500 Internal Server Error - server internal error, try later and if problem persists please contact us

GET (list all DOIs)

URI: https://mds.datacite.org/doi

This request returns a list of all DOIs for the requesting datacentre. There is no guaranteed order.

Request headers

none

Request body

empty

Response headers

none

Response body

If response status is 200: list of DOIs, one DOI per line; empty for 204

Response statuses

200 OK - operation successful

204 No Content - no DOIs founds

POST

URI: https://doidb.wdc-terra.org/mds/doi

POST will mint new DOI if specified DOI doesn't exist. This method will attempt to update URL if you specify existing DOI. Standard domains and quota restrictions check will be performed. A Datacentre's doiQuotaUsed will be increased by 1. A new record in Datasets will be created.

Request headers

Content-Type:text/plain;charset=UTF-8

Request body

doi={doi}
url={url}

where {doi} and {url} have to be replaced by your DOI and URL, UFT-8 encoded.

Response body

short explanation of status code e.g. CREATED, HANDLE_ALREADY_EXISTS etc

Response statuses

201 Created - operation successful

400 Bad Request - request body must be exactly two lines: DOI and URL; wrong domain, wrong prefix

401 Unauthorized - no login

403 Forbidden - login problem, quota exceeded

412 Precondition failed - metadata must be uploaded first

500 Internal Server Error - server internal error, try later and if problem persists please contact us

Metadata API

GET

URI: https://doidb.wdc-terra.org/mds/metadata/{doi} where {doi} is a specific DOI.

This request returns the most recent version of metadata associated with a given DOI.

Request headers

Accept:application/xml

Request body

empty

Response headers

Content-Type:application/xml

Response body

If response status is 200: XML representing a dataset, otherwise short explanation for non-200 status

Response statuses

200 OK - operation successful

401 Unauthorized - no login

403 Forbidden - login problem or dataset belongs to another party

404 Not Found - DOI does not exist in our database

410 Gone - the requested dataset was marked inactive (using DELETE method)

500 Internal Server Error - server internal error, try later and if problem persists please contact us

POST

URI: https://doidb.wdc-terra.org/mds/metadata/{doi}

This request stores new version of metadata in DOIDB and registers the metadata at DataCite. The request body must contain valid XML in DataCite, DIF, or ISO schema. For the DataCite schema you can alternatively use the URI https://doidb.wdc-terra.org/mds/metadata as endpoint, since the DOI is kept in the metadata. For DIF and ISO schema the {doi} in the URI is required and DataCite metadata is automatically generated using stylesheet transformation.

Request headers

Content-Type:application/xml;charset=UTF-8

Request body

UFT-8 encoded metadata

Response body

short explanation of status code e.g. CREATED, HANDLE_ALREADY_EXISTS etc

Response headers

Location - URL of the newly stored metadata

Response statuses

201 Created - operation successful

400 Bad Request - invalid XML, wrong prefix

401 Unauthorized - no login

403 Forbidden - login problem, quota exceeded

500 Internal Server Error - server internal error, try later and if problem persists please contact us

DELETE

URI: https://doidb.wdc-terra.org/mds/metadata/{doi} where {doi} is a specific DOI.

This request marks a dataset as 'inactive'. To activate it again, POST new metadata or set the isActive-flag in the user interface.

Response body

if response status 200 - XML representing a dataset, otherwise short explanation for non-200 status

Response statuses

200 OK - operation successful: dataset deactivated

401 Unauthorized - no login

403 Forbidden - login problem or dataset belongs to another party

404 Not Found - DOI does not exist in our database

500 Internal Server Error - server internal error, try later and if problem persists please contact us

DIFMetadata API and ISOMetadata API

Both APIs use the same commands, parameters, and returncodes as the Metadata API described above. The APIs differ from the Metadata API only in the accepted metadata schema and there is no conversion to/registration of DataCite metadata. This is done to allow independent deposition of metadata in situations where automatic conversion might not be appropriate. However, to make independent registration of ISO and DIF metadata work, DataCite metadata must already be associated with the DOI.

URI: https://doidb.wdc-terra.org/mds/isometadata/{doi} accepts ISO19139 metadata.

URI: https://doidb.wdc-terra.org/mds/difmetadata/{doi} accepts DIF metadata.

Media API

GET

URI: https://mds.datacite.org/media/{doi} where {doi} is a specific DOI.

This request returns list of pairs of media type and URLs associated with a given DOI.

Request headers

none

Request body

empty

Response headers

none

Response body

If response status is 200: key-value list of media types/urls, otherwise short explanation for non-200 status

Response statuses

200 OK - operation successful

401 Unauthorized - no login

403 login problem or dataset belongs to another party

404 Not Found - No media attached to the DOI or DOI does not exist in our database

500 Internal Server Error - server internal error, try later and if problem persists please contact us

POST

URI: https://mds.datacite.org/media/{doi} where {doi} is a specific DOI.

POST will add/update media type/urls pairs to a DOI. Standard domain restrictions check will be performed.

Request headers

Content-Type:text/plain;charset=UTF-8

Request body

Multiple lines in the following format 
{mime-type}={url}

where {mime-type} and {url} have to be replaced by your mime type and URL, UFT-8 encoded.

Response body

short explanation of status code

Response statuses

200 OK - operation successful

400 Bad Request - one or more of the specified mime-types or urls are invalid (e.g. non supported mime-type, not allowed url domain, etc.)

401 Unauthorized - no login

403 Forbidden - login problem

500 Internal Server Error - server internal error, try later and if problem persists please contact us