...
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 API Changes
Object changes:
- Creation of DoiMetadata object
- This object abstracts DataCite's more complex and granular metadata API by including only fields that are required and cannot be automatically populated.
- This object is easily extensible to further support DataCite's metadata schema to include optional fields or the introduction of new required fields
- Doi and DoiMetadata are proposed to be uncoupled because
- We store the data in Doi objects; it allows us to quickly identify if a DOI has been registered and report that to the client
- We do NOT store the data in the DoiMetadata objects; this is stored by the DOI provider and retrieved when necessary
- Caching this data seems unintuitive; retrieving this data should only be expected when a user considers updating it (see notes in table below), which requires the external service to be available anyways.
DataCite-imposed constraints:
- There cannot be more than 8000-10000 creators
- Publication year must be in 'YYYY' format (regex:
/[\d]{4}/) - The creators should be at least 1 character long
- The title should be at least one character long
In addition to the preexisting API:
...
- Should we permit creating DOIs for any object? Or just entities?
- Shifting to support DOI non-entity objects is non-trivial but it would be easier to support them sooner than later
- Schema enforcement
- Should we force users to provide required metadata to mint a DOI?
Permit and submit no metadata(this is currently the only way to mint a DOI in Synapse)- In Datacite, it is only possible to mint a DOI without metadata with the temporary EZID bridge API i.e. it will likely not be possible to mint without metadata in the near future
- Should we allow users to not supply required metadata? We could fill required fields with "mock" data. (For example, permit submitting a blank author field, and then the backend can submit "(Author not available)" to Datacite as we currently do)
- One required metadata field is ResourceTypeGeneral, which has specified categories for the type of resource a DOI refers to. Should we omit categories of resources that are likely not in Synapse? Like "Audiovisual" or "Physical Object". There is no technical benefit of excluding these fields.
- Future feature expansion: which recommended/optional metadata fields should we permit or require?
- Synapse could theoretically support all metadata fields, but for scope/UX reasons, maybe we shouldn't. Input from UX, users, anyone would be helpful.
- Should we force users to provide required metadata to mint a DOI?
- Which fields should be immutable?
- DOI ID (this can actually be retrieved from the API call rather than the request body)
- Publisher: "Synapse"
- Publication Year?
- We can make these "immutable" by not including these objects in the DoiMetadata body. The user cannot see them nor modify them, and they are handled entirely by the backend.
Mockups
TBD
Internal Design/Implementation Notes
...