Add documentation for v32.0.0

Signed-off-by: Tushar Goel <[email protected]>

docs/source/api.rst

@@ -11,6 +11,17 @@ Browse the Open API documentation
 - https://public.vulnerablecode.io/api/schema/ for the OpenAPI schema
 
 
+How to use OpenAPI documentation
+--------------------------------------
+
+The API documentation is available at https://public.vulnerablecode.io/api/docs/.
+To use the endpoints you need to authenticate with an API key. Request your API key
+from https://public.vulnerablecode.io/account/request_api_key/. Once you have
+your API key, click on the ``Authorize`` button on the top right of the page and enter
+your API key in the ``value`` field with ``Token`` prefix, so if your token is "1234567890abcdef"
+then you have to enter this: ``Token 1234567890abcdef``.
+
+
 Enable the API key authentication
 ------------------------------------
 
@@ -48,3 +59,153 @@ There are two primary endpoints:
 And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
 and vulnerability by CPEs: cpes/ and aliases/
 
+The API is paginated and the default page size is 100. You can change the page size
+by passing the page_size parameter. You can also change the page number by passing
+the page parameter.
+
+.. list-table:: Table for the API endpoints
+   :widths: 30 40 30
+   :header-rows: 1
+
+   * - Endpoint
+     - Query Parameters
+     - Expected Output
+   * - /api/vulnerabilities/
+     -
+       - vulnerability_id (string) = VCID of the vulnerability
+       - page (integer) = page number of the response
+       - page_size (integer) = number of vulnerabilities in each page
+     - Returns a list of vulnerabilities
+   * - /api/vulnerabilities/{id}
+     -
+       - id = internal primary id of the vulnerability
+     - Returns a vulnerability with the given id
+   * - /api/packages
+     -
+       - type (string) = type of the package
+       - namespace (string) = namespace of the package
+       - name (string) = name of the package
+       - version (string) = version of the package
+       - qualifiers (string) = qualifiers of the package
+       - subpath (string) = subpath of the package
+       - page (integer) = page number of the response
+       - page_size (integer) = number of packages in each page
+     - Returns a list of packages
+   * - /api/packages/{id}
+     -
+       - id = internal primary id of the package
+     - Returns a package with the given id
+   * - /api/packages/all
+     - No parameter required
+     - Returns a list of all vulnerable packages
+   * - /api/packages/bulk_search
+     - Refer to package bulk search section :ref:`Package Bulk Search`
+     - Returns a list of packages
+   * - /api/aliases
+     -
+       - alias (string) = value of the alias
+       - page (integer) = page number of the response
+       - page_size (integer) = number of aliases in each page
+     - Returns a list of vulnerabilities
+   * - /api/aliases/{id}
+     -
+       - id = internal primary id of the alias
+     - Returns an alias with the given id
+   * - /api/cpes
+     -
+       - cpe (string) = value of the cpe
+       - page (integer) = page number of the response
+       - page_size (integer) = number of cpes in each page
+     - Returns a list of vulnerabilities
+   * - /api/cpes/{id}
+     -
+       - id = internal primary id of the cpe
+     - Returns a cpe with the given id
+   * - /api/cpes/bulk_search
+     - Refer to cpe bulk search section :ref:`CPE Bulk Search`
+     - Returns a list of cpes
+
+
+.. _Package Bulk Search:
+
+Package Bulk Search
+---------------------
+
+
+The package bulk search endpoint allows you to search for packages in bulk. You can
+pass a list of packages in the request body and the endpoint will return a list of
+packages with vulnerabilities.
+
+
+You can pass a list of ``purls`` in the request body. Each package should be a
+valid purl string.
+
+You can also pass options like ``purl_only`` and ``plain_purl`` in the request.
+``purl_only`` will return only a list of vulnerable purls from the purls recieved in request.
+``plain_purl`` allows you to query API using plain purls by removing qualifiers
+and subpath from the purl.
+
+The request body should be a JSON object with the following structure::
+
+    {
+        "purls": [
+            "pkg:pypi/[email protected]",
+            "pkg:npm/[email protected]"
+        ],
+        "purl_only": false,
+        "plain_purl": false,
+    }
+
+Sample python script::
+
+    import requests
+
+    request_body = {
+        "purls": [
+            "pkg:npm/[email protected]"
+        ],
+    }
+
+    resp = requests.post('https://public.vulnerablecode.io/api/packages/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
+
+
+The response will be a list of packages with vulnerabilities
+they are affected by or fixing any vulnerability.
+
+.. _CPE Bulk Search:
+
+CPE Bulk Search
+---------------------
+
+
+The CPE bulk search endpoint allows you to search for packages in bulk.
+You can pass a list of packages in the request body and the endpoint will
+return a list of vulnerabilities.
+
+
+You can pass a list of ``cpes`` in the request body. Each cpe should be a
+non empty string and a valid CPE.
+
+
+The request body should be a JSON object with the following structure::
+
+    {
+        "cpes": [
+            "cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*",
+            "cpe:2.3:a:apache:struts:2.3.2:*:*:*:*:*:*:*"
+        ]
+    }
+
+Sample python script::
+
+    import requests
+
+    request_body = {
+        "cpes": [
+            "cpe:2.3:a:apache:struts:2.3.1:*:*:*:*:*:*:*"
+        ],
+    }
+
+    resp = requests.post('https://public.vulnerablecode.io/api/cpes/bulk_search', json= request_body, headers={'Authorization': "Token 123456789"}).json()
+
+The response will be a list of vulnerabilities that have the following CPEs.