Enumerate Inspector errors

Propose Ironic Inspector error message enumeration for
the purpose of allowing the automation around Ironic
Inspector REST API being more robust and straightforward.

Change-Id: Ib5af833224c33274e23b417da17c71825b26775b

specs/inspector-error-enumeration.rst

@@ -0,0 +1,157 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==================================
+Ironic Inspector Error Enumeration
+==================================
+
+https://bugs.launchpad.net/ironic-inspector/+bug/1710945
+
+This blueprint will introduce a new field `error-code` to the
+**Ironic Inspector** API. The new field is thought to make the automation
+around **Ironic Inspector** easier and more reliable.
+
+
+Problem description
+===================
+
+Currently, if node inspection process fails for one reason or the other,
+it may be hard for the **Ironic Inspector** REST API consumers to determine
+the exact cause of the failure. That is because the only error indication
+currently being offered by the **Ironic Inspector** REST API (other than
+HTTP error code) is a free-form error message text.
+
+.. code-block:: json
+
+    {
+        "error": {
+            "message": "Diskette drive 0 seek failure"
+        }
+    }
+
+
+Proposed change
+===============
+
+The proposal is to enumerate **Ironic Inspector** REST API errors by
+introducing a new numeric field `error-code` to the:
+
+* **Ironic Inspector** REST API
+* **Ironic Inspector** Ramdisk Callback API
+
+There is probably no need to assign a distinct `error-code` to every
+possible `error` message. Instead a handful of important classes of
+errors may be determined, then all `error` messages may be distributed
+over the `error-code` set.
+
+The collection of `error-code` values would become part of the REST
+API, documented and possibly made discoverable at the REST API itself.
+
+
+Alternatives
+------------
+
+Advise **Ironic Inspector** REST API consumers to rely upon the
+`error` messages they observe. This would constitute a somewhat toxic
+design as it effectively blocks **Ironic Inspector** developers from
+changing error messages (accidental change, rewording, localization), puts
+needless efforts on the consumers while the end product would remain
+fragile.
+
+
+Data model impact
+-----------------
+
+The **Ironic Inspector** database schema would include the new integer
+field - `error_code`.
+
+The **Ironic Inspector** REST and Ramdisk Callback API's would include
+new integer field - `error-code`.
+
+Existing database would have to be migrated onto the modified schema.
+Initial value for the new `error_code` field would be set to `<no-error>`.
+
+
+HTTP API impact
+---------------
+
+TODO(etingof): to be filled in
+
+
+Client (CLI) impact
+-------------------
+
+TODO(etingof): to be filled in
+
+
+Ironic python agent impact
+--------------------------
+
+TODO(etingof): to be filled in
+
+
+Performance and scalability impact
+----------------------------------
+
+TODO(etingof): to be filled in
+
+
+Security impact
+---------------
+
+None.
+
+
+Deployer impact
+---------------
+
+TODO(etingof): to be filled in
+
+
+Developer impact
+----------------
+
+TODO(etingof): to be filled in
+
+
+Upgrades and Backwards Compatibility
+------------------------------------
+
+TODO(etingof): to be filled in
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  <etingof>
+
+
+Work Items
+----------
+
+TODO(etingof): to be filled in
+
+
+Dependencies
+============
+
+TODO(etingof): to be filled in
+
+
+Testing
+=======
+
+TODO(etingof): to be filled in
+
+
+References
+==========
+
+None.