Change API design

api_v3_usage.rst

@@ -0,0 +1,246 @@
+Package Endpoint
+================
+
+We are migrating from **API v1** to **API v3**.
+
+Previously, the ``/api/packages`` endpoint exposed multiple routes:
+
+- ``bulk_search``
+- ``bulk_lookup``
+- ``lookup``
+- ``all``
+
+In **API v3**, all these capabilities are consolidated into a **single endpoint**:
+
+::
+
+    POST /api/v3/packages
+
+
+Pagination
+----------
+
+Responses from the package endpoint are **always paginated**, with **10 results per page**.
+
+Each response includes:
+
+- ``count`` — total number of results
+- ``next`` — URL for the next page
+- ``previous`` — URL for the previous page
+
+If a package is associated with **more than 100 advisories**, the response will include:
+
+- ``affected_by_vulnerabilities_url`` instead of ``affected_by_vulnerabilities``
+- ``fixing_vulnerabilities_url`` instead of ``fixing_vulnerabilities``
+
+
+Getting All Vulnerable Packages
+-------------------------------
+
+Instead of calling ``/api/packages/all``, call the v3 endpoint with an empty ``purls`` list.
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": []
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 596,
+        "next": "http://example.com/api/v3/packages?page=2",
+        "previous": null,
+        "results": [
+            "pkg:npm/626@1.1.1",
+            "pkg:npm/aedes@0.35.0",
+            "pkg:npm/airbrake@0.3.8",
+            "pkg:npm/angular-http-server@1.4.3",
+            "pkg:npm/apex-publish-static-files@2.0.0",
+            "pkg:npm/atob@2.0.3",
+            "pkg:npm/augustine@0.2.3",
+            "pkg:npm/backbone@0.3.3",
+            "pkg:npm/base64-url@1.3.3",
+            "pkg:npm/base64url@2.0.0"
+        ]
+    }
+
+
+Bulk Search (Replacement)
+-------------------------
+
+Instead of calling ``/api/packages/bulk_search``, use:
+
+::
+
+    POST /api/v3/packages
+
+Parameters:
+
+- ``purls`` — list of package URLs to query
+- ``details`` — boolean (default: ``false``)
+- ``approximate`` — boolean (default: ``false``)
+
+The ``approximate`` flag replaces the previous ``plain_purl`` parameter.  
+When set to ``true``, qualifiers and subpaths in PURLs are ignored.
+
+
+Get Only Vulnerable PURLs
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"],
+        "details": false
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            "pkg:npm/atob@2.0.3"
+        ]
+    }
+
+
+Get Detailed Vulnerability Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"],
+        "details": true
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            {
+                "purl": "pkg:npm/atob@2.0.3",
+                "affected_by_vulnerabilities": [
+                    {
+                        "advisory_id": "nodejs_security_wg/npm-403",
+                        "fixed_by_packages": [
+                            "pkg:npm/atob@2.1.0"
+                        ],
+                        "duplicate_advisory_ids": []
+                    }
+                ],
+                "fixing_vulnerabilities": [],
+                "next_non_vulnerable_version": "2.1.0",
+                "latest_non_vulnerable_version": "2.1.0",
+                "risk_score": null
+            }
+        ]
+    }
+
+
+Using Approximate Matching
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    POST /api/v3/packages
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3?foo=bar"],
+        "approximate": true,
+        "details": true
+    }
+
+Example response:
+
+::
+
+    {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+            {
+                "purl": "pkg:npm/atob@2.0.3",
+                "affected_by_vulnerabilities": [
+                    {
+                        "advisory_id": "nodejs_security_wg/npm-403",
+                        "fixed_by_packages": [
+                            "pkg:npm/atob@2.1.0"
+                        ],
+                        "duplicate_advisory_ids": []
+                    }
+                ],
+                "fixing_vulnerabilities": [],
+                "next_non_vulnerable_version": "2.1.0",
+                "latest_non_vulnerable_version": "2.1.0",
+                "risk_score": null
+            }
+        ]
+    }
+
+
+Advisory Endpoint
+=================
+
+Retrieve advisories for one or more PURLs:
+
+::
+
+    POST /api/v3/advisories
+
+    {
+        "purls": ["pkg:npm/atob@2.0.3", "pkg:pypi/sample@2.0.0"]
+    }
+
+Responses are paginated (10 results per page) and include ``next`` and ``previous`` links.
+
+
+Affected-By Advisories Endpoint
+===============================
+
+Retrieve advisories that **affect (impact)** a given PURL:
+
+::
+
+    GET /api/v3/affected-by-advisories?purl=<purl>
+
+Example:
+
+::
+
+    GET /api/v3/affected-by-advisories?purl=pkg:npm/atob@2.0.3
+
+
+Fixing Advisories Endpoint
+==========================
+
+Retrieve advisories that are **fixed by** a given PURL:
+
+::
+
+    GET /api/v3/fixing-advisories?purl=<purl>
+
+Example:
+
+::
+
+    GET /api/v3/fixing-advisories?purl=pkg:npm/atob@2.1.0