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
noneRequest body
emptyResponse headers
noneResponse 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
noneRequest body
emptyResponse headers
noneResponse 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
emptyResponse 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
noneRequest body
emptyResponse headers
noneResponse 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