Restructure the API docs to make triage easier to use (#169)

Related to gardenlinux/glvd#156

Author: fwilhe

src/docs/asciidoc/index.adoc

@@ -5,23 +5,59 @@ Garden Linux Authors
 :source-highlighter: highlightjs
 :toc:
 
-== Overview
-
 This document describes the HTTP API endpoints of the Garden Linux Vulnerability Database (GLVD).
 
-CAUTION: This document and the API are work in progress and subject to change at any time.
+Find out more about GLVD at https://security.gardenlinux.org and https://github.com/gardenlinux/glvd.
 
-== API Endpoints
+This document provides real HTTP requests and responses captured from API tests.
+The data shown is based on unit tests and may differ from production data, but the structure of requests and responses remains consistent.
 
-=== List All Garden Linux Releases
+== Triage Data
 
-Retrieve all known Garden Linux releases:
+Triage is the process where the Garden Linux security team evaluates security vulnerabilities (CVEs) to determine their impact on Garden Linux releases.
+Getting Triage data is one of the main features of the GLVD API.
 
-include::{snippets}/getAllGardenLinuxVersions/curl-request.adoc[]
+=== List Triages for a Garden Linux Release
+
+Retrieve triaged security vulnerabilities for a Garden Linux release.
+
+include::{snippets}/triagesGardenlinux/curl-request.adoc[]
 
 Example response:
 
-include::{snippets}/getAllGardenLinuxVersions/http-response.adoc[]
+include::{snippets}/triagesGardenlinux/http-response.adoc[]
+
+=== Get Triages for a CVE
+
+Retrieve triage information for a specific CVE by its ID.
+
+include::{snippets}/triagesCve/curl-request.adoc[]
+
+Example response:
+
+include::{snippets}/triagesCve/http-response.adoc[]
+
+=== Get Triages for a Debian Source Package
+
+Retrieve triage information for all CVEs related to a Debian source package.
+
+include::{snippets}/triagesPackage/curl-request.adoc[]
+
+Example response:
+
+include::{snippets}/triagesPackage/http-response.adoc[]
+
+=== List All Triages
+
+Retrieve a list of triages regardless of the Garden Linux release.
+
+include::{snippets}/triagesList/curl-request.adoc[]
+
+Example response:
+
+include::{snippets}/triagesList/http-response.adoc[]
+
+== CVE Data
 
 === List CVEs by Distribution
 
@@ -57,16 +93,6 @@ Example response:
 
 include::{snippets}/getCveForPackagesPut/http-response.adoc[]
 
-=== List Packages in a Distribution
-
-Retrieve a list of packages for a given distribution.
-
-include::{snippets}/getPackages/curl-request.adoc[]
-
-Example response:
-
-include::{snippets}/getPackages/http-response.adoc[]
-
 === Get Vulnerabilities for a Package
 
 Retrieve vulnerabilities for a specific package.
@@ -97,9 +123,10 @@ Example response:
 
 include::{snippets}/getPackagesByVulnerability/http-response.adoc[]
 
-=== Get CVE Details with Context
+=== Get CVE Details with Triage Data
 
 Retrieve information about a CVE by its ID.
+If triage data is available for this CVE, it is included in the response.
 
 include::{snippets}/getCveDetailsWithContexts/curl-request.adoc[]
 
@@ -130,62 +157,34 @@ Example response:
 
 include::{snippets}/getCveDetailsNonDebian/http-response.adoc[]
 
-=== Get Release Notes
-
-Retrieve information about fixed security vulnerabilities in a new minor release.
-
-include::{snippets}/releaseNotes/curl-request.adoc[]
-
-Example response:
-
-include::{snippets}/releaseNotes/http-response.adoc[]
-
-=== Get Patch Release Notes (Legacy)
-
-Retrieve information about fixed security vulnerabilities in a new patch release.
-
-include::{snippets}/patchReleaseNotes/curl-request.adoc[]
-
-Example response:
-
-include::{snippets}/patchReleaseNotes/http-response.adoc[]
-
-=== List Triages for a Garden Linux Release
-
-Retrieve triaged security vulnerabilities for a Garden Linux release.
-
-include::{snippets}/triagesGardenlinux/curl-request.adoc[]
-
-Example response:
-
-include::{snippets}/triagesGardenlinux/http-response.adoc[]
+== Garden Linux Release Data
 
-=== Get Triages for a CVE
+=== List All Garden Linux Releases
 
-Retrieve triage information for a specific CVE by its ID.
+Retrieve all known Garden Linux releases in GLVD.
 
-include::{snippets}/triagesCve/curl-request.adoc[]
+include::{snippets}/getAllGardenLinuxVersions/curl-request.adoc[]
 
 Example response:
 
-include::{snippets}/triagesCve/http-response.adoc[]
+include::{snippets}/getAllGardenLinuxVersions/http-response.adoc[]
 
-=== Get Triages for a Debian Source Package
+=== List Packages in a Distribution
 
-Retrieve triage information for all CVEs related to a Debian source package.
+Retrieve a list of packages for a given distribution.
 
-include::{snippets}/triagesPackage/curl-request.adoc[]
+include::{snippets}/getPackages/curl-request.adoc[]
 
 Example response:
 
-include::{snippets}/triagesPackage/http-response.adoc[]
+include::{snippets}/getPackages/http-response.adoc[]
 
-=== List All Triages
+=== Get Release Notes
 
-Retrieve a list of triages regardless of the Garden Linux release.
+Retrieve information about fixed security vulnerabilities in a minor release of Garden Linux.
 
-include::{snippets}/triagesList/curl-request.adoc[]
+include::{snippets}/releaseNotes/curl-request.adoc[]
 
 Example response:
 
-include::{snippets}/triagesList/http-response.adoc[]
+include::{snippets}/releaseNotes/http-response.adoc[]