Document API to mint and manage pid4cat handles

[dalito]

...in a separate markdown document.

[dalito]

Summary of development status of API v2

As of today.

Still missing

• A POST API endpoint, e.g. "/{scheme}/", to create a PID with user-provided id-suffix (e.g. provided via a query parameter). Note that there is a PUT "/{scheme}/" endpoint but PUT should not be used for creating a resource. Moreover the PUT "/{scheme}/" endpoint does not have a parameter for a user-provided id-suffix. It is suggested to replace the PUT endpoint by such new POST endpoint. Update: It is a PUT endpoint to be compatible with the original handle.net API.
  • @prestonrodrigues - FYI: EPIC / PIDINST uses POST for new user-provided suffixes and PUT for server generated suffixes.

Another observation is that the generated handles do not yet have the required structure:

<handle-prefix> / <branding-suffix> / <ns-suffix> / <id-suffix>

While the branding "4cat" is already present, the important <ns-suffix> part is missing. However, the API does not required further changes except the addition of the before-mentioned missing parameter in the API endpoint. With such API endpoint for creating user-provided IDs, the user can also create IDs comprising both parts <ns-suffix> / <id-suffix>. The server just needs to validate that the user´s POST request for creating new PIDs includes an <ns-suffix> part which the user is allowed to use.

Minor issues

• The parameter to hide the metadata is not needed. Open, CC0-licensed metadata are mandatory for pid4cat handles.
• Why do two different PUT endpoints exist for metadata? It seems that one is for json-data and the other for scalar values but why not combine them into one?
• It is suggested to rename "scheme" to be consistent with pid4cat-model terminology.
• The descriptions in the API documentation can be improved (see notes in demo that I submit as PR).

[dalito]

The API got its own repo: https://github.com/nfdi4cat/pid4cat-api/

I keep this issue open until a fully working API-version is documented in the docs of pid4cat-model.

[dalito]

FYI: We have another API which does a lot more like management of sub namespace owners incl. permissions, search etc. - This is not yet open-sourced.

Once a decisions is made which production API we will offer the documentation will be updated.