diff options
| -rw-r--r-- | docs/api.rst | 133 | ||||
| -rw-r--r-- | docs/index.rst | 1 |
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 |