Update the ucp api docs to include information about validations

Updated the error response for more clarity.

Change-Id: I0c5f57ecf2d68c3c57a1423426d2e9cf190044cc

docs/api-conventions.md

@@ -24,18 +24,29 @@ more specific to point to a particular service.
 ## Error responses
 Error responses (HTTP response body accompanying 4xx and 5xx series responses
 where possible) are a more specific version of the
-[Kubernetes standard for error representation](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md#response-status-kind). 
+[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:
-```...
-"details": {
-  "errorCount": n,
-  "errorList": [
-     { "message" : "some message text here"}
-  ]
-}
-...
+
 ```
+{
+  "kind": "Status",
+  "apiVersion": "v1",
+  "metadata": {},
+  "status": "Failure",
+  "message": "{{UCP Component Name}} {{error phrase}}",
+  "reason": "{{appropriate reason phrase}}",
+  "details": {
+    "errorCount": {{n}},
+    "errorList": [
+       { "message" : "{{validation failure message}}"},
+       ...
+    ]
+  },
+  "code": {{http status code}}
+}
+```
+
 such that:
 1. the details field is still optional
 2. if used, the details follow that format
@@ -54,3 +65,67 @@ The auth token to identify the invoking user.
 A context id that will be carried on all logs for this client-provided marker.
 This marker may only be a 36-character canonical representation of an UUID
 (8-4-4-4-12)
+
+## Validation API  
+All UCP components that participate in validation of the design supplied to a
+site implement a common resource to perform document validations. Document
+validations are syncrhonous and target completion in 30 seconds or less.
+Because of the different sources of documents that should be supported, a
+flexible input descriptor is used to indicate from where a UCP component will
+retrieve the documents to be validated.
+  
+### POST /v1.0/validatedesign  
+Invokes a UCP component to perform validations against the documents specified
+by the input structure.  Synchronous.
+
+#### Input structure  
+```
+{
+  rel : "design",
+  href: "deckhand+https://deckhand/{{revision_id}}/rendered-documents",
+  type: "application/x-yaml"
+}
+```
+#### Output structure
+The output structure reuses the Kubernetes Status kind to represent the result
+of validations. The Status kind will be returned for both successful and failed
+validation to maintain a consistent of interface. If there are additional
+diagnostics that associate to a particular validation, the entry in the error
+list may carry fields other than "message".
+
+Failure message example:
+```
+{
+  "kind": "Status",
+  "apiVersion": "v1",
+  "metadata": {},
+  "status": "Invalid",
+  "message": "{{UCP Component Name}} validations failed",
+  "reason": "Validation",
+  "details": {
+    "errorCount": {{n}},
+    "errorList": [
+       { "message" : "{{validation failure message}}"},
+       ...
+    ]
+  },
+  "code": 400
+}
+```
+
+Success message example:
+```
+{
+  "kind": "Status",
+  "apiVersion": "v1",
+  "metadata": {},
+  "status": "Valid",
+  "message": "{{UCP Component Name}} validations succeeded",
+  "reason": "Validation",
+  "details": {
+    "errorCount": 0,
+    "errorList": []
+  },
+  "code": 200
+}
+```