Adds Documentation for Notifications

This documents the account/notifications endpoint and the Notification
object

Author: Dorthu

docs/src/data/endpoints/account.yaml

@@ -435,6 +435,25 @@ endpoints:
             curl -H "Authorization: Bearer $TOKEN" \
                 -X DELETE \
                 https://$api_root/$version/account/oauth-clients/$client_id
+  /account/notifications:
+    group: Notifications
+    authenticated: true
+    description: >
+      View the collection of Notifications on your account.
+    methods:
+      GET:
+        response: notification
+        description: >
+          Returns a collection of important, often time-sensitive items related
+          to your account, such as "you have an outstanding balance" or "one of
+          your linodes has a scheduled migration."  These are infrequent, but
+          important when they do arise.
+        examples:
+          curl: |
+            curl -H "Authorization: Bearer $TOKEN" \
+                https://$api_root/$version/account/notifications
+          python: |
+            # coming soon
   /account/events:
     group: Events
     authenticated: true

docs/src/data/objects/notification.yaml

@@ -0,0 +1,56 @@
+name: Notification
+description: >
+  Notifications are important, often time-sensitive occurrences that require
+  your attention.  These include, but are not limited to, having an outstanding
+  balance, having scheduled Linode migrations, having important tickets open
+  on your account, or being impacted by a known outage.
+schema:
+  type:
+    description: >
+      The type of notification this is.
+    type: Enum
+    subtype: NotificatonType
+    value: important_ticket
+  entity:
+    description: >
+      Detailed inforrmation about the event's entity, including id, type, label, and URL used to access it.
+    type:
+      id:
+        type: Integer
+        value: 9302
+        description: >
+          The entity's ID that this event is for.  This is meaningless without a type.
+      label:
+        type: String
+        value: linode123
+        description: >
+          The current label of this object.  This will reflect changes in label.
+      type:
+        type: String
+        value: linode
+        description: >
+          The type of entity this is related to.
+      url:
+        type: String
+        value: /v4/linode/instances/123
+        description: >
+          The URL where you can access the object this event is for.  If a relative URL, it is
+          relative to the domain you retrieved the event from.
+  when:
+    description: >
+      If this notification is of an event that will happen at a fixed, future time,
+      this is when the named action will be taken.  For example, is a Linode is
+      to be migrated in response to a Xen Security Advisory, this field will
+      contain around the time the Linode will be taken offline for migration.
+    type: Datetime
+    value: null
+enums:
+  NotificatonType:
+    important_ticket: There is a ticket open on your account that requires your attention.
+    abuse_ticket: There is an abuse-related ticket on your account that requires your attention.
+    outage: There is a known outage impacting one or more of your services.
+    pending_migration: There is a migration queued for one of your Linodes that you must initiate.
+    scheduled_migration: There is a migration queued for one of your Linodes.
+    outstanding_balance: You have a balance on your account that must be paid.
+    xsa: You have a Linode impacted by a Xen Security Advisory which will require migration.
+    scheduled_reboot: There is a reboot queued for one of your Linodes.