From 0c1207a51c965aa90949b2c401ed2783830a58f4 Mon Sep 17 00:00:00 2001
From: Felipe Monteiro <felipe.monteiro@att.com>
Date: Thu, 21 Sep 2017 16:47:32 +0100
Subject: [PATCH] Versions API UCP requirement

This PS adds a new UCP requirement for each UCP component to
return a list of its API versions via GET /versions.

Change-Id: Id448abab386df1fec3f1008182d94b9cdd6923a8
---
 docs/api-conventions.md | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/api-conventions.md b/docs/api-conventions.md
index 6e6b8ef9..903c8fb9 100644
--- a/docs/api-conventions.md
+++ b/docs/api-conventions.md
@@ -132,7 +132,7 @@ Success message example:
 ```
 
 ## Health Check API
-Each UCP component shall expose an endpoint that allows other component
+Each UCP component shall expose an endpoint that allows other components
 to access and validate its health status.  The response shall be received
 within 30 seconds.
 
@@ -197,3 +197,33 @@ Success message example:
   "code": 200
 }
 ```
+
+## Versions API
+Each UCP component shall expose an endpoint that allows other components to
+discover its different API versions.
+
+### GET /versions
+Invokes a UCP component to return its list of API versions.
+
+#### Versions output
+Each UCP component shall return a list of its different API versions. The
+response body shall be keyed with the name of each API version, with
+accompanying information pertaining to the version's `path` and `status`. The
+`status` field shall be an enum which accepts the values "stable" and "beta",
+where "stable" implies a stable API and "beta" implies an under-development
+API.
+
+Success message example:
+```
+{
+  "v1.0": {
+    "path": "/api/v1.0",
+    "status": "stable"
+  },
+  "v1.1": {
+    "path": "/api/v1.1",
+    "status": "beta"
+  },
+  "code": 200
+}
+```