Merge ~jsseidel/maas:jsseidel-notifications-api-annotations into maas:master

[Spencer Seidel]

Added API annotations and examples to notifications.

[Mike Pontillo (mpontillo)]

I'm good with this branch. Just a few comments below; I'll leave it up to you regarding whether or not you think action is required on them.

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b jsseidel-notifications-api-annotations lp:~jsseidel/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: b949cc38bfe0e4724d17e0be0f57901b4d18d086

review: Approve

diff --git a/src/maasserver/api/examples/notifications.json b/src/maasserver/api/examples/notifications.json
new file mode 100644
index 0000000..1010eb3
--- /dev/null
+++ b/src/maasserver/api/examples/notifications.json
@@ -0,0 +1,132 @@
+{
+  "notifications-read": [
+    {
+      "ident": "dhcp_disabled_all_vlans",
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "DHCP is not enabled on any VLAN.  This will prevent machines from being able to PXE boot, unless an external DHCP server is being used.",
+      "context": {},
+      "category": "warning",
+      "id": 1,
+      "resource_uri": "/MAAS/api/2.0/notifications/1/"
+    },
+    {
+      "ident": null,
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "Attention admins! Core critical! Meltdown imminent! Evacuate habitat immediately!",
+      "context": {
+        "name-oeIkwE": "value-cY9eNX"
+      },
+      "category": "error",
+      "id": 2,
+      "resource_uri": "/MAAS/api/2.0/notifications/2/"
+    },
+    {
+      "ident": null,
+      "user": {
+        "is_superuser": true,
+        "username": "admin",
+        "email": "[e-mail]",
+        "is_local": true,
+        "resource_uri": "/MAAS/api/2.0/users/admin/"
+      },
+      "users": false,
+      "admins": false,
+      "message": "Greetings, {name}! Get away from the habitat for the weekend and visit the Mare Nubium with MAAS Tours. Use the code METAL to claim a special gift!",
+      "context": {
+        "name": "Admin"
+      },
+      "category": "info",
+      "id": 5,
+      "resource_uri": "/MAAS/api/2.0/notifications/5/"
+    },
+    {
+      "ident": "maas-import-pxe-files script",
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "Boot image import process not started. Machines will not be able to\nprovision without boot images. Visit the\n<a href=\"http://localhost:5240/MAAS/#/images\">boot images</a> page to start the import.\n",
+      "context": {},
+      "category": "error",
+      "id": 1409,
+      "resource_uri": "/MAAS/api/2.0/notifications/1409/"
+    },
+    {
+      "ident": "clusters",
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "One rack controller is not yet connected to the region. Visit the <a href=\"/MAAS/#/controllers\">rack controllers page</a> for more information.",
+      "context": {},
+      "category": "error",
+      "id": 1410,
+      "resource_uri": "/MAAS/api/2.0/notifications/1410/"
+    },
+    {
+      "ident": "controller_out_of_date_mfhrw8",
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "Controller <a href='#/node/controller/{system_id}'>{hostname}</a> is running an older version of MAAS (less than 2.3.0).",
+      "context": {
+        "hostname": "happy-region",
+        "latest_version": "",
+        "system_id": "mfhrw8"
+      },
+      "category": "warning",
+      "id": 1411,
+      "resource_uri": "/MAAS/api/2.0/notifications/1411/"
+    },
+    {
+      "ident": "controller_out_of_date_ekf6cn",
+      "user": null,
+      "users": false,
+      "admins": true,
+      "message": "Controller <a href='#/node/controller/{system_id}'>{hostname}</a> is running an older version of MAAS (less than 2.3.0).",
+      "context": {
+        "hostname": "happy-rack",
+        "latest_version": "",
+        "system_id": "ekf6cn"
+      },
+      "category": "warning",
+      "id": 1412,
+      "resource_uri": "/MAAS/api/2.0/notifications/1412/"
+    }
+  ],
+  "notifications-create": {
+    "ident": null,
+    "user": null,
+    "users": true,
+    "admins": false,
+    "message": "This is a test message.",
+    "context": {},
+    "category": "info",
+    "id": 1413,
+    "resource_uri": "/MAAS/api/2.0/notifications/1413/"
+  },
+  "notifications-read-by-id": {
+    "ident": null,
+    "user": null,
+    "users": true,
+    "admins": false,
+    "message": "This is a test message.",
+    "context": {},
+    "category": "info",
+    "id": 1414,
+    "resource_uri": "/MAAS/api/2.0/notifications/1414/"
+  },
+  "notifications-update": {
+    "ident": null,
+    "user": null,
+    "users": true,
+    "admins": false,
+    "message": "This is an updated test message.",
+    "context": {},
+    "category": "info",
+    "id": 1414,
+    "resource_uri": "/MAAS/api/2.0/notifications/1414/"
+  }
+}
diff --git a/src/maasserver/api/notification.py b/src/maasserver/api/notification.py
index 6def843..edf059f 100644
--- a/src/maasserver/api/notification.py
+++ b/src/maasserver/api/notification.py
@@ -44,36 +44,58 @@ class NotificationsHandler(OperationsHandler):
         return ('notifications_handler', [])
 
     def read(self, request):
-        """List notifications relevant to the invoking user.
+        """@description-title List notifications
+        @description List notifications relevant to the invoking user.
 
         Notifications that have been dismissed are *not* returned.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing a list of
+        notification objects.
+        @success-example "success-json" [exkey=notifications-read] placeholder
+        text
         """
         return Notification.objects.find_for_user(request.user).order_by('id')
 
     @admin_method
     def create(self, request):
-        """Create a notification.
+        """@description-title Create a notification
+        @description Create a new notification.
 
         This is available to admins *only*.
 
-        :param message: The message for this notification. May contain basic
-            HTML; this will be sanitised before display.
-        :param context: Optional JSON context. The root object *must* be an
-            object (i.e. a mapping). The values herein can be referenced by
-            `message` with Python's "format" (not %) codes.
-        :param category: Optional category. Choose from: error, warning,
-            success, or info. Defaults to info.
-
-        :param ident: Optional unique identifier for this notification.
-        :param user: Optional user ID this notification is intended for. By
-            default it will not be targeted to any individual user.
-        :param users: Optional boolean, true to notify all users, defaults to
-            false, i.e. not targeted to all users.
-        :param admins: Optional boolean, true to notify all admins, defaults to
-            false, i.e. not targeted to all admins.
-
-        Note: if neither user nor users nor admins is set, the notification
-        will not be seen by anyone.
+        Note: One of the ``user``, ``users`` or ``admins`` parameters must be
+        set to True for the notification to be visible to anyone.
+
+        @param (string) "message" [required=true] The message for this
+        notification. May contain basic HTML, such as formatting. This string
+        will be sanitised before display so that it doesn't break MAAS HTML.
+
+        @param (string) "context" [required=false] Optional JSON context. The
+        root object *must* be an object (i.e. a mapping). The values herein can
+        be referenced by ``message`` with Python's "format" (not %) codes.
+
+        @param (string) "category" [required=false] Choose from: ``error``,
+        ``warning``, ``success``, or ``info``. Defaults to ``info``.
+
+        @param (string) "ident" [required=false] Unique identifier for this
+        notification.
+
+        @param (string) "user" [required=false] User ID this notification is
+        intended for. By default it will not be targeted to any individual
+        user.
+
+        @param (boolean) "users" [required=false] True to notify all users,
+        defaults to false, i.e. not targeted to all users.
+
+        @param (boolean) "admins" [required=false] True to notify all admins,
+        defaults to false, i.e. not targeted to all admins.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing a new
+        notification object.
+        @success-example "success-json" [exkey=notifications-create]
+        placeholder text
         """
         form = NotificationForm(data=request.data)
         if form.is_valid():
@@ -92,7 +114,22 @@ class NotificationHandler(OperationsHandler):
     fields = DISPLAYED_NOTIFICATION_FIELDS
 
     def read(self, request, id):
-        """Read a specific notification."""
+        """@description-title Read a notification
+        @description Read a notification with the given id.
+
+        @param (int) "{id}" [required=true] The notification id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the requested
+        notification object.
+        @success-example "success-json" [exkey=notifications-read-by-id]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested notification is not found.
+        @error-example "not-found"
+            Not Found
+        """
         notification = get_object_or_404(Notification, id=id)
         if notification.is_relevant_to(request.user):
             return notification
@@ -103,9 +140,50 @@ class NotificationHandler(OperationsHandler):
 
     @admin_method
     def update(self, request, id):
-        """Update a specific notification.
+        """@description-title Update a notification
+        @description Update a notification with a given id.
+
+        This is available to admins *only*.
+
+        Note: One of the ``user``, ``users`` or ``admins`` parameters must be
+        set to True for the notification to be visible to anyone.
+
+        @param (int) "{id}" [required=true] The notification id.
 
-        See `NotificationsHandler.create` for field information.
+        @param (string) "message" [required=true] The message for this
+        notification. May contain basic HTML, such as formatting. This string
+        will be sanitised before display so that it doesn't break MAAS HTML.
+
+        @param (string) "context" [required=false] Optional JSON context. The
+        root object *must* be an object (i.e. a mapping). The values herein can
+        be referenced by ``message`` with Python's "format" (not %) codes.
+
+        @param (string) "category" [required=false] Choose from: ``error``,
+        ``warning``, ``success``, or ``info``. Defaults to ``info``.
+
+        @param (string) "ident" [required=false] Unique identifier for this
+        notification.
+
+        @param (string) "user" [required=false] User ID this notification is
+        intended for. By default it will not be targeted to any individual
+        user.
+
+        @param (boolean) "users" [required=false] True to notify all users,
+        defaults to false, i.e. not targeted to all users.
+
+        @param (boolean) "admins" [required=false] True to notify all admins,
+        defaults to false, i.e. not targeted to all admins.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        notification object.
+        @success-example "success-json" [exkey=notifications-update]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested notification is not found.
+        @error-example "not-found"
+            Not Found
         """
         notification = get_object_or_404(Notification, id=id)
         form = NotificationForm(
@@ -117,19 +195,41 @@ class NotificationHandler(OperationsHandler):
 
     @admin_method
     def delete(self, request, id):
-        """Delete a specific notification."""
+        """@description-title Delete a notification
+        @description Delete a notification with a given id.
+
+        @param (int) "{id}" [required=true] The notification id.
+
+        @success (http-status-code) "server-success" 204
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested notification is not found.
+        @error-example "not-found"
+            Not Found
+        """
         notification = get_object_or_404(Notification, id=id)
         notification.delete()
         return rc.DELETED
 
     @operation(idempotent=False)
     def dismiss(self, request, id):
-        """Dismiss a specific notification.
-
-        Returns HTTP 403 FORBIDDEN if this notification is not relevant
-        (targeted) to the invoking user.
+        """@description-title Dismiss a notification
+        @description Dismiss a notification with the given id.
 
         It is safe to call multiple times for the same notification.
+
+        @param (int) "{id}" [required=true] The notification id.
+
+        @success (http-status-code) "server-success" 200
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The notification is not relevant to the
+        invoking user.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested notification is not found.
+        @error-example "not-found"
+            Not Found
         """
         notification = get_object_or_404(Notification, id=id)
         if notification.is_relevant_to(request.user):