From 2128967be18f3c371a1d96be17e3ae457990deda Mon Sep 17 00:00:00 2001
From: Scott Hussey <sh8121@att.com>
Date: Wed, 20 Sep 2017 13:07:44 -0500
Subject: [PATCH] Generalize error response

Generalize the specified error response standard to be usable
for status responses of all kinds including detailed responses
describing actions taken to successfully satisfy a request.

Change-Id: I51970ce53c92d67d786efac226dfa62a40d0bcee
---
 docs/api-conventions.md | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/docs/api-conventions.md b/docs/api-conventions.md
index 9e921fa4..6e6b8ef9 100644
--- a/docs/api-conventions.md
+++ b/docs/api-conventions.md
@@ -21,12 +21,12 @@ more specific to point to a particular service.
      version here
 ```
 ---
-## Error responses
-Error responses (HTTP response body accompanying 4xx and 5xx series responses
-where possible) are a more specific version of the
+## Status responses
+Status responses, and more specifically error responses (HTTP response body accompanying 4xx and 5xx series responses
+where possible) are a customized version of the
 [Kubernetes standard for error representation](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#response-status-kind).
 UCP utilizes the details field in a more formalized way to represent multiple
-messages related to an error response, as follows:
+messages related to a status response, as follows:
 
 ```
 {
@@ -34,12 +34,12 @@ messages related to an error response, as follows:
   "apiVersion": "v1",
   "metadata": {},
   "status": "Failure",
-  "message": "{{UCP Component Name}} {{error phrase}}",
+  "message": "{{UCP Component Name}} {{status phrase}}",
   "reason": "{{appropriate reason phrase}}",
   "details": {
     "errorCount": {{n}},
-    "errorList": [
-       { "message" : "{{validation failure message}}"},
+    "messageList": [
+       { "message" : "{{validation failure message}}", "error": true|false},
        ...
     ]
   },
@@ -50,8 +50,9 @@ messages related to an error response, as follows:
 such that:
 1. the details field is still optional
 2. if used, the details follow that format
-3. the repeating entity inside the errorList can be decorated with as many
-other fields as are useful, but at least have a message field
+3. the repeating entity inside the messageList can be decorated with as many other fields as are useful, but at least have a message field and error field.
+4. the errorCount field is an integer representing the count of messageList entities that have `error: true`
+5. when using this document as the body of a HTTP response, `code` is populated with a valid HTTP [status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
 ---
 ## Headers
 ### Required
@@ -104,8 +105,8 @@ Failure message example:
   "reason": "Validation",
   "details": {
     "errorCount": {{n}},
-    "errorList": [
-       { "message" : "{{validation failure message}}"},
+    "messageList": [
+       { "message" : "{{validation failure message}}", "error": true},
        ...
     ]
   },
@@ -124,7 +125,7 @@ Success message example:
   "reason": "Validation",
   "details": {
     "errorCount": 0,
-    "errorList": []
+    "messageList": []
   },
   "code": 200
 }
@@ -171,8 +172,8 @@ Failure message example:
   "reason": "Health Check",
   "details": {
     "errorCount": {{n}},
-    "errorList": [
-       { "message" : "{{Detailed Health Check failure information}}"},
+    "messageList": [
+       { "message" : "{{Detailed Health Check failure information}}", "error": true},
        ...
     ]
   },
@@ -191,7 +192,7 @@ Success message example:
   "reason": "Health Check",
   "details": {
     "errorCount": 0,
-    "errorList": []
+    "messageList": []
   },
   "code": 200
 }