docs: Update HTTP API page to VyOS 1.5 standards

[LiudmylaNad]

Change Summary

This PR refactors the HTTP API page to comply with the current VyOS documentation style guide.

Changes:

• AI & SEO Context: Added :description: and :keywords: metadata tags.
• Content: Proofread and improved.
• New subsections "HTTPS listener", "TLS", and "API authentication" added under Configuration to group related commands.
• Technical accuracy: Verified commands against VyOS 1.5.
• Added examples for all commands.
• The style guide checklist was applied.

Added value range for:
set service https port <1-65535>
set service https request-body-size-limit <1-256>
set service https api graphql authentication expiration <60-31536000>
set service https api graphql authentication secret-length <16-65535>

Related Task(s)

VD-3756

Related PR(s)

Backport

Checklist:

• I have read the CONTRIBUTING document

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 620921dc-10f6-4003-9bc9-236f5939261f

📥 Commits

Reviewing files that changed from the base of the PR and between 55cb7ff and f76f0cd.

📒 Files selected for processing (1)

• docs/configuration/service/https.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• ansible/ansible (manual)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/configuration/service/https.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Mergify Merge Protections
• GitHub Check: Summary

🧰 Additional context used

🔍 Remote MCP Context7

Relevant review context

• VyOS 1.5 defaults the HTTPS listener to port 443 and the request-body limit to 1 MB. DH parameters must be at least 2048 bits; TLS 1.2 and 1.3 are supported.
• GraphQL authentication defaults to API keys (key). JWT expiration defaults to 3600 seconds, and the JWT secret length defaults to 32 bytes.
• GraphQL schema introspection is explicitly documented as a security risk when enabled in production.
• The documentation confirms the relevant configuration commands, including REST/API-key setup, GraphQL authentication type, introspection, CORS, certificates, listener address/port, and request-body limits.
• The retrieved sources do not confirm the proposed validation ranges for port, JWT expiration, or secret length. Those ranges should be verified against the actual VyOS CLI/schema definitions before merging.

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Expanded the HTTPS API guide with detailed listener configuration (address/port/VRF binding, client restrictions, HTTP→HTTPS redirects, and request size limits).
  • Broadened TLS documentation, including supported versions and certificate/CA/DH parameter setup with clearer constraints.
  • Reworked API authentication docs, detailing HTTPS API keys and HTTPS REST vs GraphQL behavior with JWT token authentication.
  • Added REST strict and debug mode explanations, plus updated examples.
  • Enhanced GraphQL documentation with schema introspection, auth mode selection, JWT lifetime/secret settings, and CORS origin allow-lists; updated minimal REST example.

Walkthrough

Rewrites docs/configuration/service/https.md with expanded HTTPS API documentation covering listener and TLS settings, authentication, REST behavior, GraphQL options, and the minimal REST configuration example.

Changes

HTTPS API Documentation

Layer / File(s)	Summary
Overview and HTTPS configuration docs/configuration/service/https.md	Adds HTML metadata and expands the HTTP API overview, HTTPS listener options, TLS settings, certificate bindings, and fallback certificate behavior (lines 1–195).
Authentication and REST API docs/configuration/service/https.md	Documents HTTPS API key requirements, GraphQL token authentication conditions, REST enablement, strict deletion handling, and debug logging (lines 196–255).
GraphQL and example configuration docs/configuration/service/https.md	Documents GraphQL introspection, authentication modes, JWT settings, CORS origins, and the minimal REST API configuration (lines 256–334).

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the HTTP API docs update for VyOS 1.5 standards.
Description check	✅ Passed	The description matches the HTTPS/API documentation refactor, examples, and value ranges.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Claude finished @LiudmylaNad's task in 3m 18s —— View job

---

VyOS Documentation Review — PR #2131

• Read Pass 1 findings (pass1-findings.json — no findings)
• Inspect changed MyST file (docs/configuration/service/https.md)
• Cross-reference vyos-1x XML/Python sources (branch: current)
• Verify command paths, defaults, and value constraints
• Post inline comments for confirmed issues
• Post final summary comment

---

Issues

• INFO — debug is a hidden CLI node (lines 242–254)
  Doc publishes set service https api rest debug as a supported command.
  Source (interface-definitions/service_https.xml.in:46-52): the debug leafNode carries <hidden/>, so it is intentionally omitted from tab-completion and treated as an internal/developer flag. Consider dropping the subsection or explicitly marking it as internal — hidden nodes generally aren't surfaced in user docs because their shape/behavior aren't API-stable. Inline comment posted.

Needs Verification

None. All other claims cross-checked cleanly against vyos-1x@current:

• port range 1–65535, default 443 (service_https.xml.in:145-147, include/port-number.xml.i) ✓
• request-body-size-limit 1–256, default 1 (service_https.xml.in:148-160) ✓
• tls-version <1.2 | 1.3>, default 1.2 1.3 — matches "both enabled by default" ✓
• graphql authentication type <key|token>, default key ✓
• graphql authentication expiration 60–31536000, default 3600 ✓
• graphql authentication secret-length 16–65535, default 32 ✓
• listen-address accepts IPv4 and IPv6 (include/listen-address.xml.i) ✓
• allow-client address accepts IPv4/IPv6 addresses and prefixes (include/allow-client.xml.i) ✓
• strict behavior — matches src/services/api/rest/routers.py:431 ✓
• debug behavior (traceback vs short error) — matches src/services/api/rest/routers.py:310-327 ✓
• dh-params "at least 2048 bits" — matches verify_pki_dh_parameters(https, tmp, 2048) at service_https.py:104 ✓
• Self-signed fallback — matches data/templates/https/nginx.default.j2:36-40 (snakeoil from ssl-cert) ✓
• enable-http-redirect port-443 caveat — matches nginx.default.j2:3-8 (return 301 https://$host$request_uri, no port) ✓
• "At least one API key required unless GraphQL JWT enabled" — matches service_https.py:148-149 ✓

Stats

• Validated 1 MyST file.
• Skipped 0 RST files awaiting MyST migration.
• Files reviewed: docs/configuration/service/https.md.
• Commands checked: ~19 (set service https ...).
• Branch reviewed: rolling (vyos-1x: current).
  | Branch: revise-http-api

[Copilot]

Pull request overview

This PR updates the HTTP API documentation page (service https) to align with current VyOS 1.5 documentation conventions, improving structure, clarity, and discoverability while adding examples and more explicit configuration guidance.

Changes:

• Added MyST html_meta (description, keywords) front matter for SEO/context.
• Reorganized the configuration section into clearer subsections (HTTPS listener, TLS, API authentication) with expanded explanations.
• Added concrete configuration examples for each documented command and clarified default behaviors.

[dmbaturin]

Looks mostly good, I just added a few small suggestions.