docs: Update HTTP API page to VyOS 1.5 standards (#2131)

* docs: Update HTTP API page to VyOS 1.5 standards

* Clarify the wording about self-signed certificates

* Fix unsual wording regarding DH parameters configuration

* Update https.md

---------

Co-authored-by: Daniil Baturin <daniil@baturin.org>

1 files changed, 247 insertions, 47 deletions

diff --git a/docs/configuration/service/https.md b/docs/configuration/service/https.md
index 184fd088..83d13d5a 100644
--- a/docs/configuration/service/https.md
+++ b/docs/configuration/service/https.md
@@ -1,136 +1,336 @@
+---
+myst:
+  html_meta:
+    description: |
+      VyOS provides an HTTP API for running operational-mode commands
+      and managing configuration. The API is available as both REST and
+      GraphQL, served by an HTTPS listener with configurable TLS.
+    keywords: http-api, https, rest, graphql, api-key, jwt, tls, cors
+---
+
 (http-api)=
 
 # HTTP API
 
-VyOS provide an HTTP API. You can use it to execute op-mode commands,
-update VyOS, set or delete config.
+VyOS provides an HTTP API. You can use it to run operational-mode
+commands or to change or delete configuration. The API is available as
+both a REST API and a GraphQL API.
+
+For REST API request examples, endpoints, and authentication details,
+see {ref}`vyosapi`.
 
-Please take a look at the {ref}`vyosapi` page for an detailed how-to.
+```{note}
+If no PKI certificate is configured for the service, VyOS automatically
+generates a self-signed certificate. This is not recommended for production use.
+```
 
 ## Configuration
 
-```{cfgcmd} set service https allow-client address \<address\>
+### HTTPS listener
+
+```{cfgcmd} set service https listen-address \<address\>
+
+**Configure a local IPv4 or IPv6 address on which the HTTPS listener
+accepts incoming connections.**
+
+The IP address must already be assigned to a local interface. Repeat
+the command to configure multiple IP addresses.
 
-Only allow certain IP addresses or prefixes to access the https
-webserver.
+When unset, the listener accepts incoming connections on all local IP
+addresses.
 ```
 
-```{cfgcmd} set service https certificates ca-certificate \<name\>
+Example:
 
-Use CA certificate from PKI subsystem
+```none
+set service https listen-address 192.0.2.1
+set service https listen-address 2001:db8::1
 ```
 
-```{cfgcmd} set service https certificates certificate \<name\>
+```{cfgcmd} set service https port \<1-65535\>
+
+**Configure the TCP port on which the HTTPS listener accepts incoming
+connections.**
 
-Use certificate from PKI subsystem
+The default is 443.
 ```
 
-```{cfgcmd} set service https certificates dh-params \<name\>
+```{note}
+If the chosen port is already in use by another service, the commit
+fails.
+```
+
+Example:
 
-Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem.
-Must be at least 2048 bits in length.
+```none
+set service https port 8443
 ```
 
-```{cfgcmd} set service https listen-address \<address\>
+```{cfgcmd} set service https vrf \<name\>
+
+**Bind the HTTPS listener to the specified
+{abbr}`VRF (Virtual Routing and Forwarding)` instance.**
+
+The VRF must already be configured under `set vrf name <name>`.
+```
+
+Example:
 
-Webserver should only listen on specified IP address
+```none
+set service https vrf mgmt
 ```
 
-```{cfgcmd} set service https port \<number\>
+```{cfgcmd} set service https allow-client address \<address\>
+
+**Restrict access to the HTTPS API endpoints to the specified IPv4 or
+IPv6 address or prefix.**
 
-Webserver should listen on specified port.
+Repeat the command to allow multiple IP addresses or prefixes.
 
-Default: 443
+When unset, the API accepts connections from any IP address.
+```
+
+Example:
+
+```none
+set service https allow-client address 192.0.2.0/24
+set service https allow-client address 2001:db8::/32
 ```
 
 ```{cfgcmd} set service https enable-http-redirect
 
-Enable automatic redirect from http to https.
+**Enable redirection of incoming HTTP requests (port 80) to HTTPS.**
+
+The redirect sends traffic to the default HTTPS port (443). If you
+have changed the HTTPS port, the redirect will not work.
+```
+
+Example:
+
+```none
+set service https enable-http-redirect
 ```
 
+```{cfgcmd} set service https request-body-size-limit \<1-256\>
+
+**Configure the maximum size, in megabytes, of an HTTP request body
+accepted by the listener.**
+
+Requests exceeding this limit are rejected.
+
+The default is 1.
+```
+
+Example:
+
+```none
+set service https request-body-size-limit 10
+```
+
+### TLS
+
 ```{cfgcmd} set service https tls-version \<1.2 | 1.3\>
 
-Select TLS version used.
+**Enable a specific TLS protocol version for the HTTPS listener.**
 
-This defaults to both 1.2 and 1.3.
+Repeat the command to enable multiple protocol versions.
+
+By default, both TLS 1.2 and TLS 1.3 are enabled.
 ```
 
-```{cfgcmd} set service https vrf \<name\>
+Example:
+
+```none
+set service https tls-version 1.3
+```
+
+```{cfgcmd} set service https certificates certificate \<name\>
 
-Start Webserver in given VRF.
+**Bind a TLS certificate from the PKI subsystem to the HTTPS
+listener.**
+
+The certificate must already be defined under
+`set pki certificate <name>` with both a certificate and a private
+key.
 ```
 
-```{cfgcmd} set service https request-body-size-limit \<size\>
+Example:
 
-Set the maximum request body size in megabytes. Default is 1MB.
+```none
+set service https certificates certificate my-server-cert
 ```
 
+```{cfgcmd} set service https certificates ca-certificate \<name\>
 
-### API
+**Bind a {abbr}`CA (Certificate Authority)` certificate from the PKI
+subsystem to the HTTPS listener.**
+
+The CA must already be defined under `set pki ca <name>`. The CA
+certificate is appended to the TLS certificate to form a full chain
+presented to clients during the TLS handshake.
+```
+
+Example:
+
+```none
+set service https certificates ca-certificate my-internal-ca
+```
+
+```{cfgcmd} set service https certificates dh-params \<name\>
+
+**Choose Diffie-Hellman parameters from the PKI subsystem for the HTTPS
+listener.**
+
+The parameters must already be defined under `set pki dh <name>` with
+a key size of at least 2048 bits. The parameters are used by DHE
+cipher suites in TLS 1.2. TLS 1.3 does not use them.
+```
+
+Example:
+
+```none
+set service https certificates dh-params my-dh-2048
+```
+
+### API authentication
 
 ```{cfgcmd} set service https api keys id \<name\> key \<apikey\>
 
-Set a named api key. Every key has the same, full permissions
-on the system.
+**Configure an HTTP API key to authenticate REST requests, and GraphQL
+requests unless GraphQL is switched to JWT token authentication.**
+
+The key is specified in plaintext and grants full access to the API.
+
+At least one key must be configured to use the REST API. GraphQL can
+run without keys if JWT token authentication is enabled.
 ```
 
+Example:
+
+```none
+set service https api keys id MY-HTTPS-API-ID key 'MY-HTTPS-API-PLAINTEXT-KEY'
+```
 
 ### REST
 
 ```{cfgcmd} set service https api rest
 
-Enable REST API
+**Enable the REST API for managing VyOS over HTTPS.**
 ```
 
-```{cfgcmd} set service https api rest debug
+Example:
 
-To enable debug messages. Available via {opcmd}`show log` or
-{opcmd}`monitor log`
+```none
+set service https api rest
 ```
 
 ```{cfgcmd} set service https api rest strict
 
-Enforce strict path checking.
+**Reject delete requests on the `/configure` endpoint when the target
+configuration path does not exist.**
+
+Without this flag, such requests succeed silently.
+```
+
+Example:
+
+```none
+set service https api rest strict
 ```
 
+```{cfgcmd} set service https api rest debug
+
+**Log detailed error messages to the systemd journal when API
+configuration requests fail.**
+
+Without this flag, only short error messages are logged.
+```
+
+Example:
+
+```none
+set service https api rest debug
+```
 
 ### GraphQL
 
 ```{cfgcmd} set service https api graphql introspection
 
-Enable GraphQL Schema introspection.
+**Enable GraphQL schema introspection.**
+
+Authenticated clients can then query the endpoint for the full schema.
+Disabled by default, and typically kept disabled in production due to
+security concerns.
 ```
 
-:::{note}
-Do not leave introspection enabled in production, it is a security risk.
-:::
+Example:
+
+```none
+set service https api graphql introspection
+```
 
 ```{cfgcmd} set service https api graphql authentication type \<key | token\>
 
-Set the authentication type for GraphQL, default option is key. Available options are:
-* ``key`` use API keys configured in ``service https api keys``
-* ``token`` use JWT tokens.
+**Configure the authentication type for GraphQL requests:**
+
+- `key`: Uses the API keys configured in `service https api keys`.
+- `token`: Uses {abbr}`JWT (JSON Web Token)` tokens.
+
+The default is `key`.
+```
+
+Example:
+
+```none
+set service https api graphql authentication type token
+```
+
+```{cfgcmd} set service https api graphql authentication expiration \<60-31536000\>
+
+**Configure the lifetime, in seconds, of JWT tokens.**
+
+The default is 3600.
+```
+
+Example:
+
+```none
+set service https api graphql authentication expiration 86400
 ```
 
-```{cfgcmd} set service https api graphql authentication expiration
+```{cfgcmd} set service https api graphql authentication secret-length \<16-65535\>
+
+**Configure the length, in bytes, of the shared secret used to sign
+JWT tokens.**
 
-Set the lifetime for JWT tokens in seconds. Default is 3600 seconds.
+The default is 32.
 ```
 
-```{cfgcmd} set service https api graphql authentication secret-length
+Example:
 
-Set the byte length of the JWT secret. Default is 32.
+```none
+set service https api graphql authentication secret-length 64
 ```
 
 ```{cfgcmd} set service https api graphql cors allow-origin \<origin\>
 
-Allow cross-origin requests from \<origin\>.
+**Configure which websites (origins) can read responses from the
+GraphQL API in a browser, using
+{abbr}`CORS (Cross-Origin Resource Sharing)`.**
+
+Repeat the command to allow multiple origins.
 ```
 
+Example:
+
+```none
+set service https api graphql cors allow-origin https://app.example.com
+```
 
-## Example Configuration
+## Example
 
-Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint.
+The minimal configuration for a working REST API requires enabling REST
+and configuring at least one API key:
 
 ```none
 set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY