nexB
Plan shift to the latest advisory based API and UI and deprecating V1 API
- First, announce that we are deprecating https://public.vulnerablecode.io/api/ and ask users to migrate to https://public.vulnerablecode.io/api/v2/
- Migrate all of our importers from V1 (aka vulnerability pipelines) to V2 pipelines (aka advisory pipelines) https://github.com/aboutcode-org/vulnerablecode/issues/1881
- Document and announce the advisory API endpoints and advisory-based UI
What can we do to explain the differences and offer advice about how to migrate?
What can we do to explain the differences and offer advice about how to migrate?
We can have some documentation explaining why we have this new API format, what are the new endpoints and which old endpoint they are replacing (some kind of table) and some documentation/code on how to use these new endpoints.
For example: We have /v1/packages. We can explain why we introduced /v2/packages. What are the changes in V2 format and V1 format both at the input and output side. And how can someone use /v2/packages.
We need to prepare this documentaion and put this with a banner on our production, README, CHANGELOG and other documentation sources telling our users that we are deprecating V1 soon enough and how they can shift to V2.
@TG1999 My take on the plan would be:
- Prepare documentation, explain transition and document deprecation timeline
- Announce this on AboutCode.org (<-- @adaaaam how do we do this)
- Announce this here on the repo
- do it!
We should also announce this prominently at https://public.vulnerablecode.io/
I have a few questions:
- Out of these 3 APIs, v1 (vuln-based) slow, v2(vuln-based) fast, v3(advisory-based) (staging)
- Out of these 2 UIs v1(vuln-based), v2(advisory-based) (staging)
- For continous tracking of this data we have V1 based pipelines (vuln-based) and V2 based pipelines(advisory-based)
Which we are gonna keep for the future and get rid of?
IMO we should plan to keep advisory based UI and API, and get rid of V1, V2 API and V1 UI. Since mixing of advisories to form vulnerabilities was never a good idea. And if we want to keep both vuln and advisory based data we need to write 2 pipelines which is another maintence issues. So we should move directly to advisory based UI and API.
Thoughts ?
- Deprecate the V1 API first. Announce and release. (Announce by End of year, and retired by end of January)
- Once we are done with the migration to Advisory-based systems completely
- Put advisory based UI and API in production
- Ensuring we update Dejacode and other consumers
- Announce deprecation for vuln-based API and UI (3/6 months)
- We will deprecate V2 API and V1 UI together
- We will remove code, models and V1 based pipelines
@TG1999 Your plan seems pretty good, but I am a bit worried about the Dec/Jan timeframe for deprecating the V1 API. Since most people currently using the API are using V1 we likely need a longer support period for V1 and V2 in parallel esp. because Dec/Jan is a holiday period in NA/Europe with many people on leave. We should also think about reaching out to ally communities like ORT whose code likely depends on the V1 API and will need time to make the transition.