Ideas for more openapi.yaml improvements

KellyStathis commented 3 weeks ago

DOI registration and updates (`POST /dois` and `PUT /dois/{id}`

Task: Add links back to our main support docs (guides) and the schema documentation. Purpose: Help new REST API users get started with DOI registration.

This would improve these pages:

Specific places to improve:

[x] "event" - link back to DOI states, explain the state changes. we covered this in the training for Open Repositories (internal link to google slides) with the table explaining how events relate to state changes. we can also incorporate this into the main docs.
[x] "schemaVersion" - technically this can be set by the user but it doesn't need to be, either remove or clarify.
[x] "xml" - add or link to explanation of how this works - base64 encoding, can be included instead of json attributes, etc
[x] "prefix", "suffix", "doi" - which of these are required to register a doi? which do you need for a random suffix vs supplying a suffix? add or link to explanation
[x] all metadata properties - link to relevant schema docs explaining allowed values etc
- as part of this, I'm working on having the schema docs be at https://datacite-metadata-schema.readthedocs.io/en/4/ for all properties so this won't need to be updated when 4.6 comes out. A redirect is already in place for /4/ to /4.5/
[x] "url": define that this is the URL to which the DOI resolves

Retrieval of "clients" and "providers"

Task: Add explanation of what clients and providers are in the DataCite model and how to search them. Purpose: Help users understand how clients and providers relate to organizations and repositories and how to search them

Specific places to improve:

[ ] add links to support docs (note this lives in readme, not openapi.yaml)
[ ] explain what is searched by the query parameter - which fields of the client/provider models are covered?

Activities

Task: link back to provenance docs Purpose: Clarify what activities are

Specific places to improve:

[x] add links to support docs for provenance (note this lives in readme, not openapi.yaml)
[ ] explain what an activity is on the page

KellyStathis commented 2 weeks ago

Started work on this today, some notes:

For testing, I found it easiest to use ReadMe where I've created a hidden API reference import that points to my working branch (e.g. https://dash.readme.com/project/datacite/v1.6/refs/dois). This can be refreshed at https://dash.readme.com/project/datacite/v1.6/reference.
The "responses" are in general not accurately documented here and the examples are incomplete. I started on revising the /activities, /clients, and /providers endpoints to at least capture the difference between a list and singleton response.
Still need to review the contents of the singletons - for example, the Provider component is missing many attributes.

KellyStathis commented 2 weeks ago

What's left to review:

[x] /dois response
[x] /dois/{id} response
[x] /events request
[x] /events response
[x] /events/{id} request
[x] /events/{id} response
[x] /prefixes/totals (returning 204?)
[ ] /reports request (skipped, not familiar)
[x] /reports response
[x] /reports/{id} request
[x] /reports{id} response
[ ] any remaining examples - defer
[x] /dois{id} parameters including publisher, affiliation (for GET, POST, PUT)

datacite / lupo