vcio-api-v3: Create, stabilize and debug new API v3. Organise user migrations to new API and UI.

We need to design an updated API with improved performance and refactored around the advisory x package centric data modes, (and then later migrated importers) and we need to run extensive reviews, tests and debugging and update models accordingly:

Then we need to organize user migrations to the latest v3 package and advisory API and UI, and plan the deprecation v1 and v2 API, and publish updated documentation. This means to document and announce the advisory API endpoints and advisory-based UI; announce that we are deprecating old https://public.vulnerablecode.io/api/ and ask users to migrate to https://public.vulnerablecode.io/api/v2/

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

@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

@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.

All done, see sub issues for details!

Navigation Menu

Repository navigation

vcio-api-v3: Create, stabilize and debug new API v3. Organise user migrations to new API and UI. #2025

14 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

vcio-api-v3: Create, stabilize and debug new API v3. Organise user migrations to new API and UI. #2025

Description

Activity

mjherzog commented on Nov 18, 2025

TG1999 commented on Nov 19, 2025

pombredanne commented on Nov 20, 2025

mjherzog commented on Nov 20, 2025

TG1999 commented on Dec 2, 2025

TG1999 commented on Dec 2, 2025

mjherzog commented on Dec 2, 2025

14 remaining items

pombredanne commented on Aug 24, 2026

pombredanne commented on Sep 28, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions