What endpoints should api.gsd.id support?

[joshbuker]

Open question for the community: What endpoints should api.gsd.id support?

Per @kurtseifried we should replicate the OSV API at minimum. (search & get single ID)

Per #159, we should also specify how to request a GSD ID, as well as create/update a GSD ID directly.

[joshbuker]

What about an index? Dashboard / high priority / other types of feeds?

I know for https://data.gsd.id, something like a "top 10" endpoint that gives interesting / high activity / relevant IDs would be useful for a dashboard view on the landing page.

[joshbuker]

Per OSV Schema, it seems vulns/<id> is a common endpoint for serving based on ID/alias

https://ossf.github.io/osv-schema/#id-modified-fields

e.g. https://api.gsd.id/v1/vulns/GHSA-vp9c-fpxx-744v should resolve the associated GSD (once we start ingesting GHSA's that don't have an associated CVE)

[joshbuker]

This "should" always resolve to a single ID, as any duplicates should be withdrawn and redirected to a single ID with an alias.

[kurtseifried]

I think there are 3 main areas:

1. read
2. write to existing ID
3. search (data contents and meta data)
4. create new ID

read would largely be "give me GSD-X in format-Y" (e.g. RAW, OSV, CVE4, CVE5)

write would be the edit button basically but via API so scripts/etc can do it at scale

search would be searching content (e.g. give me anything "Linux Kernel" bu product, CPE, pURL, etc.) and meta data (give me anything updated since time X, or created since time Y)

create new ID requires search to reduce duplicates (e.g. search existing URL's/content to suggest likely matches, allow the user to proceed)

we would need to also determine things like do we let people grab more than one ID at a time? If so how many? I would suggest for simplicity we just do one per request for now and make the client loop through it.

for search in the short term we could do an RSS feed that is essentially the git log of:

time, IDs affected (files), who did it, what happened (git log)

[joshbuker]

A real-world example of what's being used Python-wise: PyGithub/PyGithub#2483
And GHSA Rest API: https://docs.github.com/en/rest/security-advisories?apiVersion=2022-11-28