Work in progress, nothing on this page should be considered finalized at this point
Background & Motivation
See Meredith Slota (Unlicensed)'s 1-pager and the epic issue:
...
| URL | HTTP Verb | Description | Request Object | Response Object | Notes |
|---|---|---|---|---|---|
| /entity/{id}/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. | DoiMetadata (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. The workflow for the business logic required to register and update a DOI with DataCite is similar. If no DoiMetadata object is provided, we may choose to submit "N/A" fields (pending discussion on if this is appropriate) | |
/entity/{id}/version/{versionNumber}/doi/async/start | POST | Ditto; For a specific entity version | DoiMetadata | AsyncJobId | Ditto |
| /entity/{id}/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 | After the job completes, this should be be identical in function to the existing GET calls. | |
| /entity/{id}/version/{versionNumber}/doi/async/get/{asyncToken} | GET | Ditto; For a specific entity version | None | Ditto | |
| /entity/{id}/doi/metadata | GET | Get the metadata associated with a DOI Object, if it exists. Note: The caller must have the ACCESS_TYPE.UPDATE permission on the Entity to make this call. | None | DoiMetadata | Can be used to populate the metadata fields of an object that has a DOI, since that data is stored on DataCite. We restrict this to users that can update the data because it should only be used for update purposes; if an unprivileged user wants to retrieve the metadata for an object, they should use the DOI provider's public API. |
Note: the Doi object has a DoiStatus field, we need to evaluate how that should be handled with asynchronous workers (we can would probably just deprecate that field in favor of using AsynchronousJobStatus).
Required Involvement and Timeline
...