DOAJ: a new major version of the API to be released on 18th June 2024

[Dominic Mitchell]

A new major version (v4) of our API is scheduled for release on 18th June 2024. This new version of the API introduces significant performance improvements on the bulk article upload endpoint (/api/bulk/articles).

This change is not backwards compatible with the existing API version, so if you rely on bulk article uploads, you will need to upgrade your integrations to use the new version.

This upgrade affects only the /api/bulk/articles endpoint. If you do not use this feature, your API integrations will continue to work normally.

The bulk articles endpoint will change from a synchronous upload to an asynchronous one. In the new version, you will upload a batch of articles to be ingested, and the system will respond immediately with an "Accepted" response, and a link to a status endpoint which will track the import progress of your request. This has been done for several reasons:

1. It is consistent with the manual bulk upload approach we have in the user interface
2. It allows us to manage the performance of the API better
3. It mitigates issues some users have had with large uploads timing out

The documentation for the new API version will be published on our website at https://doaj.org/api/v4/docs. Once it is released, we will make further announcements.

Timeline

18 June 2024 - v4 of the API will be released and available at the base URL /api/v4. It will not replace the existing current API version (v3). If you are reliant on the bulk article upload, you should:

1. Try out the new bulk endpoint; upgrade your integrations immediately if feasible.
2. If upgrading your integrations in the short term is not feasible, you should fix your existing integration to point to /api/v3, which will continue to work in the medium term.

Approximately 1 month after 18th June 2024 (exact date to be confirmed) The v4 API will become the "current" API version and will be available at /api AND /api/v4. At this point, old integrations with the bulk article upload will cease to work, and you must switch to using /api/v3 if you want to get it to work again. If you wish to continue using this feature long-term, you must upgrade your integrations.

Approximately 6 months after 18th June 2024 (exact date to be confirmed) All previous API versions (v1, v2 and v3) will cease to support bulk article uploads, and if you wish to use this feature, you must use the v4 API. All other backwards-compatible API features in those previous versions of the API will continue to work as normal.

Please get in touch if you have any questions.