...
We should strongly consider deprecating these calls in favor of the new API, below
URL | HTTP Type | Description | Response Object | Notes |
|---|---|---|---|---|
| /entity/{id}/doi | PUT | Creates a DOI for the specified entity. The DOI will associated with the most recent version where applicable. | Doi | Deprecate in favor of corresponding POST |
| /entity/{id}/version/{versionNumber}/doi | PUT | Creates a new DOI for the specified entity version. | Doi | Deprecate, ditto |
| /entity/{id}/doi | GET | Gets the DOI status for the specified entity. | Doi | Maintain, as this will not require a call to another service and should be relatively quick |
| /entity/{id}/version/{versionNumber}/doi | GET | Gets the DOI status for the specified entity version. | Doi | Maintain, ditto |
Proposed Changes
Object changes:
- Extension Creation of Doi object (and creation of child objects)Extensions serve two purposesAllow the client to DoiV2 object that implements new interfaces DataciteDoi and DoiAssociation
- DataciteDoi
- Separates DOI metadata (that is stored by DataCite) from Synapse-associated metadata
- The client never uses this object
- DoiAssociation
- Stores Synapse-associated metadata of a DOI object (like the object ID, etag, etc.)
- Client can request this object to quickly get a DOI without relying on DataCite to supply metadata.
- By using DoiV2:
- The client can supply and update metadata
- Decouple We decouple our API URI from /entity/{id}
- }
- DataciteDoi
- Creation of DoiRequest object to retrieve a DOI and all of its metadataCreation of DoiId object to quickly retrieve a DOI without reliance on collecting metadata from DataCite's service
The new fields in object is a direct mapping of the most recent version (v4.1) of DataCite's metadata schema, simplified to contain only required fields and a small amount of optional fields that we curate. This ensures that we don't need to deprecate our API if we wish to support more of their optional metadata fields. If we do wish to support new optional metadata fields, we can easily extend our object.
Similarly, this is likely to simplify future transitions if DataCite deprecates the schema that we configure to use.
Existing fields in italics
DataCite-imposed constraints for implementing clients to consider:
- There cannot be more than 8000-10000 creators
- Publication year must be in 'YYYY' format (regex:
/[\d]{4}/) - There must be at least one creator
- Each creator must have a creatorName that is at least 1 character long
- nameIdentifier is not required, but if an identifier is provided, the scheme must also be provided
- There must be at least one title
- The title should be at least one character long
- There must be a resourceTypeGeneral
...
| URL | HTTP Verb | Description | Request Object | Response Object | Notes |
|---|---|---|---|---|---|
| /doi/async/start | POST | Asynchronously create or update a DOI. If the DOI does not exist, start a DOI creation job that will attempt to register a DOI with the DOI provider with the supplied metadata. If the DOI does exist, then it will simply update the DOI with the supplied metadata. Note: The caller must have the ACCESS_TYPE.UPDATE permission on the Entity to make this call. | Doi (application/json) | Shift the work to an asynchronous worker queue (as we have been doing with other asynchronous services). We combine the create and update calls because they require the same information and are both idempotent. The Doi object must contain all fields required to mint or update a DOI with DataCite. | |
| /doi/async/get/{asyncToken} | GET | Asynchronously get the results of a DOI transaction started with POST /entity/{id}/doi/async/start Note: When the result is not ready yet, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus object. | None | Get the status of the asynchronous job. If complete, returns the Doi object created by the job. | |
| /doi | GET | Get a Doi object (including associated metadata) for the object referred to in DoiRequest, if the Doi object exists. | DoiRequest | Doi | This call relies on availability of DataCite's API to return the metadata, as we do not store it. |
| /doi/id | GET | Get a DoiId object that contains the DOI of an object referred to in DOI. | DoiRequest | DoiId (reduction of Doi)DoiAssociation | By making this call, a client can get the DOI of an object without relying on DataCite's API. |
...
For the sake of not having to do more work later, we are opting to not use DataCite's temporary EZ API that is designed to mock the EZID API.
Instead, we will be using their standard MDS API, as we would need to transition to it eventually anyways.
HTTP Client
The current EZID client interfaces with EZID using now-deprecated implementations of Apache's HTTP client. We will replace this client with a new client that will use our SimpleHttpClient to make requests to the DataCite MDS API.
CRUD Workflows
With the MDS API the basic workflow to create a DOI is to
...