New features in the deps.dev API
In April 2023, we launched the first public version of the deps.dev API, v3alpha, complementing the deps.dev website and BigQuery dataset as a new way of exploring our software supply chain data. Since then, the API has served billions of requests, enabling applications like providing a richer view of SBOM data in GUAC or reporting dependency licenses in OSV-Scanner. Today, we’re adding a few of our most frequently requested features, along with a new version of the API that comes with a stability guarantee.
A new stable version
When we launched the first public version of the API, we named it v3alpha to indicate that it might change over time. In practice, we haven’t needed to make any incompatible changes to it since launch. Today, we’re formalizing our approach to API stability.
First, we’re launching a new version, v3, that comes with a stability guarantee: we will never make incompatible changes to it. It also comes with a deprecation policy: if and when we deprecate the API in favor of a newer version, we will give at least 6 months notice. Deprecations will be announced on this blog, on our documentation site, and on our GitHub repo. The v3 API has almost exactly the same structure as v3alpha has had, with only a few small tweaks to fix inconsistencies and set it up for planned—compatible—changes, and is also available via gRPC or HTTP. We recommend that most users migrate to it.
Second, with v3 providing a stable option, our existing v3alpha API can be a bit more experimental. This means that most new features will start out in the v3alpha API, possibly change in incompatible ways in response to user feedback, and eventually graduate to the v3 API.
Batch request support
First among the experimental features we’re adding to the v3alpha API is a highly requested one: batch support. Many applications currently require making hundreds of API requests for a single user task—such as fetching licenses and security advisories for all your dependencies—which can be cumbersome. With our new GetVersionBatch and GetProjectBatch endpoints, you can instead make a single request containing a batch of identifiers, and get the results in a paginated response.
Purl support
The next new experimental feature is also one requested by users: support for fetching package- or version-level data by purl. Purls, or package URLs, are widely used identifiers for packages and versions from a number of ecosystems, including the six that we currently support. By adding purl support to the API, we hope to lower the barrier to integrate it into existing workflows. Combining our two new features, we’re also adding an endpoint for requesting batches of versions by purl.
But wait, there’s more!
In addition to these brand new features, we’re also filling a few gaps. You can now find packages with similar names, previously launched on the deps.dev website, using the GetSimilarlyNamedPackages endpoint in the v3alpha API. We’ve made OSS-Fuzz data available from the GetProject endpoint in both the v3 and v3alpha APIs. We’ve also added more data showing how package versions and projects relate to each other, whether by metadata or by SLSA attestations, so users can decide whether the link is trustworthy for their application. SLSA attestations are now also verified by us.
To get started using any of the new API features mentioned in this post, check out the documentation, or visit our GitHub repo for code examples and the gRPC service definition.