Deprecation of returning all assets via the API #14140
Description
Hey folks!
Proposal
Moving forward, the cdnjs API endpoint /libraries/:library will no longer return assets for all versions of the library in the assets array. Instead, this array will only contain a single item with the assets for the latest version of the library.
The cdnjs API provides, and will continue to provide, the /libraries/:library/:version endpoint that will allow you to access assets and SRI hashes for a specific version of any library, and the versions property of the /libraries/:library endpoint response will continue to list all versions.
We hope this change will be non-breaking for most folks, as the type signature of the response from the endpoint will not be changing, only the number of items in the assets array being reduced to one, the latest version.
Justification
The reason behind us making this change and deprecating the full array in this response is simple -- it doesn't scale. As we look to move the cdnjs API to be a Cloudflare Worker instead of an Express server, we're more aware than ever of the resource usage behind each request hitting the cdnjs API and this array was proving to be a hard blocker for migrating to Workers.
For some libraries, like mathjax, this array contained 45 versions, with some containing over 25 thousand files (repeated essentially three times as we return both the files and rawFiles properties, plus SRI hashes), resulting in the response being upwards of 100MB of raw JSON data. This resulted in resource consumption that proved problematic for our Express server, and a complete blocker for a Worker.
Our work to move the cdnjs API to Cloudflare Workers is part of ongoing high-priority work to improve the stability of the cdnjs API, which has recently had issues resulting in incidents declared and bad responses returned to consumers.
Timeline
| Date | Delta | Action | Status |
|---|---|---|---|
| 2022/06/15 | - | Proposal posted | ✅ Posted |
| 2022/06/18 | +0.5 weeks | Updated Worker with single-version assets array will be pushed live to a small % of requests. | ✅ 10% rollout |
| 2022/06/25 | +1.5 weeks | If no issues arise, Worker will be ramped up to 100% of traffic with the single-version assets array over a period of a week. | ✅ 100% rollout completed (delayed, 2022/07/18 [+4.5 weeks]) |
Due to this deprecation not resulting in a type signature change to the endpoint, our belief that removing old versions from the response is unlikely to impact many (if any) API consumers, and it resolving an active technical blocker for improving API stability, we've introduced a shortened timeline for this deprecation.