Make clear that InvenioRDM API is also supported and what else changed with the latest Zenodo release

[elichad]

The API quickstart docs haven't been updated significantly since Zenodo moved to InvenioRDM, which I really didn't expect for such a large and widely-used project - I assumed that the docs would be fully up to date by now. Because of this, it's extremely difficult to find any information about what the October release changed with regards to the API or APIs available. For example:

1. should devs use the InvenioRDM API data format for new projects now?
2. will the original Zenodo API documented in the guide be deprecated at some point, or will it be maintained in parallel?
3. can I mix and match old and new data formats in API requests?

I would have really benefited from (at the very least) some sort of notice at the top of the quickstart guide explaining that the current docs are out of date and pointing to the InvenioRDM API docs.

[slint]

Hi @elichad. The lack of updates has been somewhat done purposefully since we still want to communicate that the existing REST API documentation is the official way to manage uploads on Zenodo at the moment and that the behavior has not changed after the migration. If you've noticed differences in behavior that break existing tools or workflows, these should be considered as bugs and be reported either via our support line or via GitHub issues.

To answer your questions more precisely:

1. should devs use the InvenioRDM API data format for new projects now?

At the moment, we cannot provide official support for the new InvenioRDM REST APIs. The documentation is still not entirely finished/up-to-date, which we feel would cause even further confusion. We recently announced a v12 release candidate for InvenioRDM, and we're organizing with the community efforts on documentation.

New features of Zenodo/InvenioRDM are only available via the new REST API, which I'll touch a bit further down my response.

2. will the original Zenodo API documented in the guide be deprecated at some point, or will it be maintained in parallel?

After the InvenioRDM REST API documentation is in a good state and can be integrated into our Zenodo REST API documentation (we still need to find the best way to achieve that since Zenodo might have its own customizations/extensions), we'll start explicitly monitoring access to the original Zenodo REST API.

Based on overall usage for users and key integrations, we'll then come up with a deprecation plan to communicate to users. We expect a relatively "generous" deprecation period, i.e. we're going to keep the original Zenodo REST API up and running probably for more than a year from the time of the deprecation announcement. After that we'll still keep monitoring usage and if necessary re-evaluate and extend the deprecation period or individually contact users and communities that still use deprecated REST APIs. Our goal is to avoid breaking existing integrations and workflows, communicate clearly what's happening and when, and allow plenty of time for users to upgrade.

3. can I mix and match old and new data formats in API requests?

Part of our strategy is to not backport new features of Zenodo/InvenioRDM to the "old" REST API. This also means that we can't guarantee that mixing old and new REST API calls and formats will produce consistent results, and should be used at users' own risk.

This is our way to also "push" the community towards adopting the new REST APIs, in order to benefit from new features.

I hope this sheds some light to the situation. Let me know if you have any further questions.