summaryrefslogtreecommitdiffstats
path: root/docs/sections/offeredapis.rst
diff options
context:
space:
mode:
authorFrank Sandoval <frank.sandoval@oamtechnologies.com>2018-09-06 16:30:49 -0600
committerFrank Sandoval <frank.sandoval@oamtechnologies.com>2018-09-06 16:31:05 -0600
commitb3c8241bfeebac1a7e1fd99091e89fab514973c2 (patch)
tree9f4b1c89afc65aceed3b5137f76803bfcb543a0a /docs/sections/offeredapis.rst
parentb8d070b64894975f915d01fb3baf401f2411eb3a (diff)
add has swagger doc
Issue-ID: OPTFRA-283 Change-Id: I078f3a4d89c248c0d3c306431065e27ec5422350 Signed-off-by: Frank Sandoval <frank.sandoval@oamtechnologies.com>
Diffstat (limited to 'docs/sections/offeredapis.rst')
-rw-r--r--docs/sections/offeredapis.rst470
1 files changed, 5 insertions, 465 deletions
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
index 9ffb6fb..497f9a3 100644
--- a/docs/sections/offeredapis.rst
+++ b/docs/sections/offeredapis.rst
@@ -1,478 +1,18 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
Offered APIs
=============================================
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
-
-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:string | A name for the |
-| (Optional) | | | new 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`` | plain | csapi:UUID | The UUID of |
-| (Optional) | | | the plan. UUID |
-| | | | is assigned by |
-| | | | Conductor if |
-| | | | no id is |
-| | | | provided in |
-| | | | the request. |
-+--------------------+-------+------------+-------------------+
-| ``transaction_id`` | plain | csapi:UUID | The |
-| | | | transaction id |
-| | | | assigned by |
-| | | | MSO. The logs |
-| | | | should have |
-| | | | this |
-| | | | transaction id |
-| | | | for tracking |
-| | | | purposes. |
-+--------------------+-------+------------+-------------------+
-| ``files`` | plain | xsd:dict | Supplies the |
-| (Optional) | | | contents of |
-| | | | files |
-| | | | referenced in |
-| | | | the template. |
-| | | | Conductor |
-| | | | templates can |
-| | | | explicitly |
-| | | | reference |
-| | | | files by using |
-| | | | the |
-| | | | ``get_file`` |
-| | | | intrinsic |
-| | | | function. The |
-| | | | value is a |
-| | | | JSON object, |
-| | | | where each key |
-| | | | is a relative |
-| | | | or absolute |
-| | | | URI which |
-| | | | serves as the |
-| | | | name of a |
-| | | | file, and the |
-| | | | associated |
-| | | | value provides |
-| | | | the contents |
-| | | | of the file. |
-| | | | Additionally, |
-| | | | some template |
-| | | | authors encode |
-| | | | their user |
-| | | | data in a |
-| | | | local file. |
-| | | | The Homing |
-| | | | client (e.g., |
-| | | | a CLI) can |
-| | | | examine the |
-| | | | template for |
-| | | | the |
-| | | | ``get_file`` |
-| | | | intrinsic |
-| | | | function |
-| | | | (e.g., |
-| | | | ``{get_file: f |
-| | | | ile.yaml}``) |
-| | | | and add an |
-| | | | entry to the |
-| | | | ``files`` map |
-| | | | with the path |
-| | | | to the file as |
-| | | | the name and |
-| | | | the file |
-| | | | contents as |
-| | | | the value. Do |
-| | | | not use this |
-| | | | parameter to |
-| | | | provide the |
-| | | | content of the |
-| | | | template |
-| | | | located at the |
-| | | | ``template_url`` |
-| | | | address. |
-| | | | Instead, use |
-| | | | the |
-| | | | ``template`` |
-| | | | parameter to |
-| | | | supply the |
-| | | | template |
-| | | | content as |
-| | | | part of the |
-| | | | request. |
-+--------------------+-------+------------+-------------------+
-| ``template_url`` | plain | xsd:string | A URI to |
-| (Optional) | | | the location |
-| | | | containing the |
-| | | | template on |
-| | | | which to |
-| | | | perform the |
-| | | | operation. See |
-| | | | the |
-| | | | description of |
-| | | | the |
-| | | | ``template`` |
-| | | | parameter for |
-| | | | information |
-| | | | about the |
-| | | | expected |
-| | | | template |
-| | | | content |
-| | | | located at the |
-| | | | URI. This |
-| | | | parameter is |
-| | | | only required |
-| | | | when you omit |
-| | | | the |
-| | | | ``template`` |
-| | | | parameter. If |
-| | | | you specify |
-| | | | both |
-| | | | parameters, |
-| | | | this parameter |
-| | | | is ignored. |
-+--------------------+-------+------------+-------------------+
-| ``template`` | plain | xsd:string | The template |
-| | | or xsd:dict| on which to |
-| | | | perform the |
-| | | | operation. See |
-| | | | the Homing |
-| | | | Template |
-| | | | Guide |
-| | | | for complete |
-| | | | information on |
-| | | | the format. |
-| | | | This parameter |
-| | | | is either |
-| | | | provided as a |
-| | | | ``string`` or |
-| | | | ``dict`` in |
-| | | | the JSON |
-| | | | request body. |
-| | | | For ``string`` |
-| | | | content it may |
-| | | | be a JSON- or |
-| | | | YAML-formatted |
-| | | | Conductor |
-| | | | template. For |
-| | | | ``dict`` |
-| | | | content it |
-| | | | must be a |
-| | | | direct JSON |
-| | | | representation |
-| | | | of the |
-| | | | Conductor |
-| | | | template. This |
-| | | | parameter is |
-| | | | required only |
-| | | | when you omit |
-| | | | the |
-| | | | ``template_url`` |
-| | | | parameter. If |
-| | | | you specify |
-| | | | both |
-| | | | parameters, |
-| | | | this value |
-| | | | overrides the |
-| | | | ``template_url`` |
-| | | | parameter |
-| | | | value. |
-+--------------------+-------+------------+-------------------+
-| ``timeout`` | plain | xsd:number | The timeout |
-| (Optional) | | | for plan |
-| | | | creation in |
-| | | | minutes. |
-| | | | Default is 1. |
-+--------------------+-------+------------+-------------------+
-| ``limit`` | plain | xsd:number | The maximum |
-| (Optional) | | | number of |
-| | | | recommendations |
-| | | | to return. |
-| | | | Default is 1. |
-+--------------------+-------+------------+-------------------+
-
-**NOTE**: ``files``, ``template_url``, and ``timeout`` are not yet
-supported.
+To view API documentation in the interactive swagger UI download the following and
+paste into the swagger tool here: https://editor.swagger.io
-Response Parameters
-~~~~~~~~~~~~~~~~~~~
+:download:`oof-has-api.json <./swaggerdoc/oof-has-api.json>`
-+--------------------+----------+------------+--------------------+
-| Parameter | Style | Type | Description |
-+====================+==========+============+====================+
-| ``plan`` | plain | xsd:dict | The ``plan`` |
-| | | | object. |
-+--------------------+----------+------------+--------------------+
-| ``id`` | plain | csapi:UUID | The UUID of |
-| | | | the plan. |
-+--------------------+----------+------------+--------------------+
-| ``transaction_id`` | plain | csapi:UUID | The |
-| | | | transaction id |
-| | | | assigned by |
-| | | | the MSO. |
-+--------------------+----------+------------+--------------------+
-| ``name`` | plain | xsd:string | The plan name. |
-| | | | |
-+--------------------+----------+------------+--------------------+
-| ``status`` | plain | xsd:string | The plan |
-| | | | status. One of |
-| | | | ``template``, |
-| | | | ``translated``, |
-| | | | ``solving``, |
-| | | | ``solved``, or |
-| | | | ``error``. See |
-| | | | **Plan |
-| | | | Status** table |
-| | | | for |
-| | | | descriptions |
-| | | | of each value. |
-+--------------------+----------+------------+--------------------+
-| ``message`` | plain | xsd:string | Additional |
-| | | | context, if |
-| | | | any, around |
-| | | | the message |
-| | | | status. If the |
-| | | | status is |
-| | | | ``error``, |
-| | | | this may |
-| | | | include a |
-| | | | reason and |
-| | | | suggested |
-| | | | remediation, |
-| | | | if available. |
-+--------------------+----------+------------+--------------------+
-| ``links`` | plain | xsd:list | A list of URLs |
-| | | | for the plan. |
-| | | | Each URL is a |
-| | | | JSON object |
-| | | | with an |
-| | | | ``href`` key |
-| | | | indicating the |
-| | | | URL and a |
-| | | | ``rel`` key |
-| | | | indicating its |
-| | | | relationship |
-| | | | to the plan in |
-| | | | question. |
-| | | | There may be |
-| | | | multiple links |
-| | | | returned. The |
-| | | | ``self`` |
-| | | | relationship |
-| | | | identifies the |
-| | | | URL of the |
-| | | | plan itself. |
-+--------------------+----------+------------+--------------------+
-| ``recommendations``| plain | xsd:list | A list of one |
-| | | | or more |
-| | | | recommendationS. |
-| | | | A |
-| | | | recommendation |
-| | | | pairs each |
-| | | | requested |
-| | | | demand with an |
-| | | | inventory |
-| | | | provider, a |
-| | | | single |
-| | | | candidate, and |
-| | | | an opaque |
-| | | | dictionary of |
-| | | | attributes. |
-| | | | Refer to the |
-| | | | Demand |
-| | | | candidate |
-| | | | schema in the |
-| | | | Homing |
-| | | | Template |
-| | | | Guide |
-| | | | for further |
-| | | | details. (Note |
-| | | | that, when |
-| | | | ``inventory_type`` |
-| | | | is ``cloud`` |
-| | | | the |
-| | | | candidate's |
-| | | | ``candidate_id`` |
-| | | | field is |
-| | | | redundant and |
-| | | | thus omitted.) |
-+--------------------+----------+------------+--------------------+
-
-Plan Status
-~~~~~~~~~~~
-
-+----------------+-----------------+
-| Status | Description |
-+================+=================+
-| ``template`` | Plan request |
-| | and homing |
-| | template have |
-| | been received. |
-| | Awaiting |
-| | translation. |
-+----------------+-----------------+
-| ``translated`` | Homing |
-| | template has |
-| | been |
-| | translated, |
-| | and candidates |
-| | have been |
-| | obtained from |
-| | inventory |
-| | providers. |
-| | Awaiting |
-| | solving. |
-+----------------+-----------------+
-| ``solving`` | Search for a |
-| | solution is in |
-| | progress. This |
-| | may |
-| | incorporate |
-| | requests to |
-| | service |
-| | controllers |
-| | for additional |
-| | information. |
-+----------------+-----------------+
-| ``solved`` | Search is |
-| | complete. A |
-| | solution with |
-| | one or more |
-| | recommendations |
-| | was found. |
-+----------------+-----------------+
-| ``not found`` | Search is |
-| | complete. No |
-| | recommendations |
-| | were found. |
-+----------------+-----------------+
-| ``error`` | An error was |
-| | encountered. |
-+----------------+-----------------+
+.. swaggerv2doc:: ./swaggerdoc/oof-has-api.json
State Diagram
^^^^^^^^^^^^^