google / google/osv.dev

Clarify documentation of return format for /v1/querybatch API

Open
#466 6 comments 1 reaction 1 assignee Assigned to @michaelkedar View on GitHub
api cleanup documentation infra
Dominant language
Go
Stars
2.9k
Forks
369
Avg merge
1d 17h
Merged PRs (30d)
149

Description

According to the Swagger documentation at https://osv.dev/docs/#operation/OSV_QueryAffectedBatch the endpoint `https://api.osv.dev/v1/querybatch` should return a list of `osvVulnerability`.

Instead it returns a list of vulnerability IDs without any vulnerability details or the actual link to the package the vulnerability belongs to.

This leads to the following issues:
- The batch endpoint does not return the OSV format, leading to clients having a need to query those vulnerability IDs. This completely goes against the idea of having a batch endpoint where you get all info for a set of libraries in a single HTTP request so that you do not overload the service.
- It is unclear and undocumented how the current response from the batch endpoint should be used. How to link these vulnerability IDs to the actual packages that were provided in the request?
- The documentation and implementation are out of sync

Example:
```
cat <

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.