summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorShankar Narayanan <snarayanan@research.att.com>2018-02-28 16:14:13 -0500
committerShankar Narayanan <snarayanan@research.att.com>2018-02-28 16:14:29 -0500
commit49dec11b867c895228b3f8b2f1e2e94913835b0e (patch)
treea284fc8ef07b5fdd96df1b6bd7e50f351202deda /docs
parent69dda22c24d32535c96030a1b74c04cb64963b93 (diff)
Add API documentation for optf-has
Add the API documentation exposed by HAS, used by OSDF in R2. Issue-ID: OPTFRA-155 Change-Id: I78fa78f26720ee4670fc62c250c2c4720aca2a77 Signed-off-by: Shankar Narayanan <snarayanan@research.att.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/api.rst133
-rw-r--r--docs/index.rst1
2 files changed, 134 insertions, 0 deletions
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..dba217f
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,133 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Homing API v1
+=============
+
+*Updated: 28 Feb 2018*
+
+This document describes the Homing API, provided by the Homing and Allocation service (Conductor).
+It is a work in progress and subject to frequent revision.
+
+General API Information
+=======================
+
+Authenticated calls that target a known URI but that use an HTTP method
+the implementation does not support return a 405 Method Not Allowed
+status. In addition, the HTTP OPTIONS method is supported for each known
+URI. In both cases, the Allow response header indicates the supported
+HTTP methods. See the API Errors section for more information about the
+error response structure.
+
+API versions
+============
+
+List all Homing API versions
+----------------------------
+
+**GET** ``/``\ F
+
+**Normal response codes:** 200
+
+.. code:: json
+
+ {
+ "versions": [
+ {
+ "status": "EXPERIMENTAL",
+ "id": "v1",
+ "updated": "2016-11-01T00:00:00Z",
+ "media-types": [
+ {
+ "base": "application/json",
+ "type": "application/vnd.onap.homing-v1+json"
+ }
+ ],
+ "links": [
+ {
+ "href": "http://has.ip/v1",
+ "rel": "self"
+ },
+ {
+ "href": "http://has.url/",
+ "type": "text/html",
+ "rel": "describedby"
+ }
+ ]
+ }
+ ]
+ }
+
+This operation does not accept a request body.
+
+Plans
+=====
+
+Create a plan
+-------------
+
+**POST** ``/v1/plans``
+
+- **Normal response codes:** 201
+- **Error response codes:** badRequest (400), unauthorized (401),
+ internalServerError (500)
+
+Request an inventory plan for one or more related service demands.
+
+The request includes or references a declarative **template**,
+consisting of:
+
+- **Parameters** that can be referenced like macros
+- **Demands** for service made against inventory
+- **Locations** that are common to the overall plan
+- **Constraints** made against demands, resulting in a set of inventory
+ candidates
+- **Optimizations** to further narrow down the remaining candidates
+
+The response contains an inventory **plan**, consisting of one or more
+sets of recommended pairings of demands with an inventory candidate’s
+attributes and region.
+
+Request Parameters
+~~~~~~~~~~~~~~~~~~
+
++--------------------+------------+----------+------------------------+
+| Parameter | Style | Type | Description |
++====================+============+==========+========================+
+| ``name`` | plain | xsd:stri | A name for the new |
+| (Optional) | | ng | plan. If a name is not |
+| | | | provided, it will be |
+| | | | auto-generated based |
+| | | | on the homing |
+| | | | template. This name |
+| | | | must be unique within |
+| | | | a given Conductor |
+| | | | environment. When |
+| | | | deleting a plan, its |
+| | | | name will not become |
+| | | | available for reuse |
+| | | | until the deletion |
+| | | | completes |
+| | | | successfully. Must |
+| | | | only contain letters, |
+| | | | numbers, hypens, full |
+| | | | stops, underscores, |
+| | | | and tildes (RFC 3986, |
+| | | | Section 2.3). This |
+| | | | parameter is |
+| | | | immutable. |
++--------------------+------------+----------+------------------------+
+| ``id`` (Optional) | plain | csapi:UU | The UUID of the plan. |
+| | | ID | UUID is assigned by |
+| | | | Conductor if no id is |
+| | | | provided in the |
+| | | | request. |
++--------------------+------------+----------+------------------------+
+| ``transaction_id`` | plain | csapi:UU | The transaction id |
+| | | ID | assigned by SO. The |
+| | | | logs should have this |
+| | | | transaction id for |
+| | | | tracking purposes. |
++--------------------+------------+----------+------------------------+
+| ``files`` | plain | xsd:dict | Supplies the contents |
+| (Optional) | | | of files referenced. |
++--------------------+------------+----------+------------------------+ \ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 636f71e..2ea9c0f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,4 +6,5 @@ Optimization Framework: Homing and Allocation
.. toctree::
:maxdepth: 4
+ api
release-notes/index