docs/api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 Homing API v1
   4 =============
   5
   6 *Updated: 28 Feb 2018*
   7
   8 This document describes the Homing API, provided by the Homing and Allocation service (Conductor).
   9 It is a work in progress and subject to frequent revision.
  10
  11 General API Information
  12 =======================
  13
  14 Authenticated calls that target a known URI but that use an HTTP method
  15 the implementation does not support return a 405 Method Not Allowed
  16 status. In addition, the HTTP OPTIONS method is supported for each known
  17 URI. In both cases, the Allow response header indicates the supported
  18 HTTP methods. See the API Errors section for more information about the
  19 error response structure.
  20
  21 API versions
  22 ============
  23
  24 List all Homing API versions
  25 ----------------------------
  26
  27 **GET** ``/``\ F
  28
  29 **Normal response codes:** 200
  30
  31 .. code:: json
  32
  33     {
  34       "versions": [
  35         {
  36           "status": "EXPERIMENTAL",
  37           "id": "v1",
  38           "updated": "2016-11-01T00:00:00Z",
  39           "media-types": [
  40             {
  41               "base": "application/json",
  42               "type": "application/vnd.onap.homing-v1+json"
  43             }
  44           ],
  45           "links": [
  46             {
  47               "href": "http://has.ip/v1",
  48               "rel": "self"
  49             },
  50             {
  51               "href": "http://has.url/",
  52               "type": "text/html",
  53               "rel": "describedby"
  54             }
  55           ]
  56         }
  57       ]
  58     }
  59
  60 This operation does not accept a request body.
  61
  62 Plans
  63 =====
  64
  65 Create a plan
  66 -------------
  67
  68 **POST** ``/v1/plans``
  69
  70 -  **Normal response codes:** 201
  71 -  **Error response codes:** badRequest (400), unauthorized (401),
  72    internalServerError (500)
  73
  74 Request an inventory plan for one or more related service demands.
  75
  76 The request includes or references a declarative **template**,
  77 consisting of:
  78
  79 -  **Parameters** that can be referenced like macros
  80 -  **Demands** for service made against inventory
  81 -  **Locations** that are common to the overall plan
  82 -  **Constraints** made against demands, resulting in a set of inventory
  83    candidates
  84 -  **Optimizations** to further narrow down the remaining candidates
  85
  86 The response contains an inventory **plan**, consisting of one or more
  87 sets of recommended pairings of demands with an inventory candidate’s
  88 attributes and region.
  89
  90 Request Parameters
  91 ~~~~~~~~~~~~~~~~~~
  92
  93 +--------------------+------------+----------+------------------------+
  94 | Parameter          | Style      | Type     | Description            |
  95 +====================+============+==========+========================+
  96 | ``name``           | plain      | xsd:stri | A name for the new     |
  97 | (Optional)         |            | ng       | plan. If a name is not |
  98 |                    |            |          | provided, it will be   |
  99 |                    |            |          | auto-generated based   |
 100 |                    |            |          | on the homing          |
 101 |                    |            |          | template. This name    |
 102 |                    |            |          | must be unique within  |
 103 |                    |            |          | a given Conductor      |
 104 |                    |            |          | environment. When      |
 105 |                    |            |          | deleting a plan, its   |
 106 |                    |            |          | name will not become   |
 107 |                    |            |          | available for reuse    |
 108 |                    |            |          | until the deletion     |
 109 |                    |            |          | completes              |
 110 |                    |            |          | successfully. Must     |
 111 |                    |            |          | only contain letters,  |
 112 |                    |            |          | numbers, hypens, full  |
 113 |                    |            |          | stops, underscores,    |
 114 |                    |            |          | and tildes (RFC 3986,  |
 115 |                    |            |          | Section 2.3). This     |
 116 |                    |            |          | parameter is           |
 117 |                    |            |          | immutable.             |
 118 +--------------------+------------+----------+------------------------+
 119 | ``id`` (Optional)  | plain      | csapi:UU | The UUID of the plan.  |
 120 |                    |            | ID       | UUID is assigned by    |
 121 |                    |            |          | Conductor if no id is  |
 122 |                    |            |          | provided in the        |
 123 |                    |            |          | request.               |
 124 +--------------------+------------+----------+------------------------+
 125 | ``transaction_id`` | plain      | csapi:UU | The transaction id     |
 126 |                    |            | ID       | assigned by SO. The    |
 127 |                    |            |          | logs should have this  |
 128 |                    |            |          | transaction id for     |
 129 |                    |            |          | tracking purposes.     |
 130 +--------------------+------------+----------+------------------------+
 131 | ``files``          | plain      | xsd:dict | Supplies the contents  |
 132 | (Optional)         |            |          | of files referenced.   |
 133 +--------------------+------------+----------+------------------------+