Merge ~lloydwaltersj/maas:api-landing-page into maas:master

[Jack Lloyd-Walters]

Add API landing page

[MAAS Lander (maas-lander)]

UNIT TESTS
-b api-landing-page lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/130/consoleText
COMMIT: 2bd256e598efca53938789baa5528c821129c2c7

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b api-landing-page lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 3799f2adaf1b47330ad8d1881680d35814b4485d

review: Approve

1fa18bb... by Jack Lloyd-Walters on 2022-07-21

inline json

[MAAS Lander (maas-lander)]

UNIT TESTS
-b api-landing-page lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/134/consoleText
COMMIT: 1fa18bbfd1a8fb90f2201c38524c560a36289da2

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b api-landing-page lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 1fa18bbfd1a8fb90f2201c38524c560a36289da2

review: Approve

[Alexsander de Souza (alexsander-souza)]

+1

review: Approve

6e079a9... by Jack Lloyd-Walters on 2022-07-22

initialize at once

[MAAS Lander (maas-lander)]

UNIT TESTS
-b api-landing-page lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 6e079a9a9f3ca631f50a611a559e37f01eea800c

review: Approve

diff --git a/src/maasserver/api/doc.py b/src/maasserver/api/doc.py
index 6bc7ae2..4e5c3d4 100644
--- a/src/maasserver/api/doc.py
+++ b/src/maasserver/api/doc.py
@@ -36,6 +36,35 @@ def get_api_description():
     return description
 
 
+def get_api_landing_page():
+    """Return the API landing page"""
+    description = {
+        "title": "MAAS API",
+        "description": "API landing page for MAAS",
+        "resources": [
+            {
+                "path": "/MAAS/api",
+                "rel": "self",
+                "type": "application/json",
+                "title": "this document",
+            },
+            {
+                "path": "/MAAS/api/2.0/openapi.yaml",
+                "rel": "service-desc",
+                "type": "application/openapi+yaml",
+                "title": "the API definition",
+            },
+            {
+                "path": "/MAAS/docs/api.html",
+                "rel": "service-doc",
+                "type": "text/html",
+                "title": "the API documentation",
+            },
+        ],
+    }
+    return description
+
+
 def find_api_resources(urlconf=None):
     """Find the API resources defined in `urlconf`.
 
diff --git a/src/maasserver/api/doc_handler.py b/src/maasserver/api/doc_handler.py
index 3dd41c6..f8e5ba8 100644
--- a/src/maasserver/api/doc_handler.py
+++ b/src/maasserver/api/doc_handler.py
@@ -71,6 +71,7 @@ from maasserver.api.doc import (
     generate_pod_types_doc,
     generate_power_types_doc,
     get_api_description,
+    get_api_landing_page,
 )
 from maasserver.api.templates import APITemplateRenderer
 from maasserver.utils import build_absolute_uri
@@ -242,3 +243,19 @@ def describe(request):
         json.dumps(description, sort_keys=True),
         content_type="application/json",
     )
+
+
+def api_landing_page(request):
+    """Render a landing page with pointers for the MAAS API.
+
+    :return: An `HttpResponse` containing a JSON page with pointers to both
+        human-readable documentation and api definitions.
+    """
+    description = get_api_landing_page()
+    for link in description["resources"]:
+        link["href"] = build_absolute_uri(request, link["path"])
+    # Return as a JSON document
+    return HttpResponse(
+        json.dumps(description),
+        content_type="application/json",
+    )
diff --git a/src/maasserver/api/tests/test_doc.py b/src/maasserver/api/tests/test_doc.py
index 5873438..cb9d061 100644
--- a/src/maasserver/api/tests/test_doc.py
+++ b/src/maasserver/api/tests/test_doc.py
@@ -2,6 +2,7 @@
 # GNU Affero General Public License version 3 (see the file LICENSE).
 
 from inspect import getdoc
+import json
 import random
 import types
 from unittest.mock import sentinel
@@ -40,7 +41,7 @@ from maasserver.api.doc import (
     generate_power_types_doc,
     get_api_description,
 )
-from maasserver.api.doc_handler import render_api_docs
+from maasserver.api.doc_handler import api_landing_page, render_api_docs
 from maasserver.api.support import (
     operation,
     OperationsHandler,
@@ -79,6 +80,19 @@ class TestGetAPIDescription(MAASTestCase):
         mock_get_api_description_hash.assert_called_once()
 
 
+class TestLandingPage(MAASTestCase):
+    def test_links(self):
+        request = factory.make_fake_request()
+        landing_page = api_landing_page(request)
+        content = json.loads(landing_page.content)
+        resources = content["resources"]
+        host = request.get_host()
+        for link in resources:
+            href = f"http://{host}{link['path']}"
+            self.assertEqual(link["href"], href)
+        self.assertEqual(resources[0]["type"], landing_page["content-type"])
+
+
 class TestFindingResources(MAASTestCase):
     """Tests for API inspection support: finding resources."""
 
diff --git a/src/maasserver/urls.py b/src/maasserver/urls.py
index 72bc2be..404dc11 100644
--- a/src/maasserver/urls.py
+++ b/src/maasserver/urls.py
@@ -9,6 +9,7 @@ from django.urls import include, re_path
 from django.views.generic import TemplateView
 
 from maasserver import urls_api
+from maasserver.api.doc_handler import api_landing_page
 from maasserver.bootresources import (
     simplestreams_file_handler,
     simplestreams_stream_handler,
@@ -76,6 +77,7 @@ urlpatterns += [re_path(r"^accounts/logout/$", logout, name="logout")]
 
 # API URLs. If old API requested, provide error message directing to new API.
 urlpatterns += [
+    re_path(r"^api/$", api_landing_page),
     re_path(r"^api/2\.0/", include(urls_api)),
     re_path(
         r"^api/version/",