Table of contents

DataCite API v2 for datacentres

Purpose

The purpose of this document is to explain how to register datasets via our RESTful API. Registration is open for research organisations (datacentres) associated with DataCite members (allocators). Before you will be able to use our API you must apply for an account with our service - please contact your local allocator.

Audience

This document and the API is meant for use by a technical audience. You will need a working knowledge of programming and the HTTP protocol.

Overview

The API is implemented in RESTful style. The end point for v2 you are going to use is:

https://mds.datacite.org

At the moment there are three resources:

/doi

/metadata

/media

The URI https://mds.datacite.org/doi accepts requests with POST HTTP method.

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

The URI https://mds.datacite.org/metadata accepts requests with POST HTTP method.

The URI https://mds.datacite.org/metadata/{doi}, where {doi} is an actual DOI, accepts requests with 2 HTTP methods: 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

All the traffic goes via HTTPS - please remember we do not support bare HTTP. All the requests to this system require HTTP Basic authentication header. You will get your username and password from your local DataCite allocator. Each account have some constraints associated with it:
  • 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
  • you might not be able to mint unlimited number of DOIs, there is a quota assigned to you by your allocator (the quota can be extended or lifted though)

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

Metadata about your datasets must conform to the standards published by DataCite at Metadata Schema Repository. you will find there the preferred version and exmaple XML document. Please remember that all your documents must specify correct schema location in the root element.. Also make sure DOI specified in your document matches DOI of the dataset.

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 (a specific DOI)

URI: https://mds.datacite.org/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://mds.datacite.org/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://mds.datacite.org/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://mds.datacite.org/metadata

This request stores new version of metadata. The request body must contain valid XML.

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://mds.datacite.org/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

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