summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/sections/offeredapis.rst470
-rw-r--r--docs/sections/swaggerdoc/oof-has-api.json341
2 files changed, 346 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
^^^^^^^^^^^^^
diff --git a/docs/sections/swaggerdoc/oof-has-api.json b/docs/sections/swaggerdoc/oof-has-api.json
new file mode 100644
index 0000000..dcb2aeb
--- /dev/null
+++ b/docs/sections/swaggerdoc/oof-has-api.json
@@ -0,0 +1,341 @@
+{
+ "swagger" : "2.0",
+ "info" : {
+ "description" : "This is the ONAP OOF HAS (Homing and Allocation Service) API",
+ "version" : "1.0.0",
+ "title" : "HAS API",
+ "contact" : {
+ "email" : "frank.sandoval@oamtechnologies.com"
+ },
+ "license" : {
+ "name" : "Apache 2.0",
+ "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
+ }
+ },
+ "securityDefinitions" : {
+ "basicAuth" : {
+ "type" : "basic",
+ "description" : "HTTP Basic Auth"
+ }
+ },
+ "security" : [ {
+ "basicAuth" : [ ]
+ } ],
+ "paths" : {
+ "/" : {
+ "get" : {
+ "summary" : "retrieve versions",
+ "operationId" : "retrieveVersions",
+ "description" : "retrieve supported versions of the API",
+ "security" : [ ],
+ "produces" : [ "application/json" ],
+ "responses" : {
+ "200" : {
+ "description" : "list of supported versions",
+ "schema" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/Versions"
+ }
+ }
+ },
+ "400" : {
+ "description" : "bad request",
+ "schema" : {
+ "$ref" : "#/definitions/Error"
+ }
+ },
+ "401" : {
+ "description" : "unauthorized request"
+ }
+ }
+ }
+ },
+ "/v1/plans" : {
+ "post" : {
+ "summary" : "create a plan",
+ "operationId" : "createPlan",
+ "description" : "creates a plan from one or more service demands",
+ "consumes" : [ "application/json" ],
+ "produces" : [ "application/json" ],
+ "parameters" : [ {
+ "in" : "body",
+ "name" : "demand",
+ "description" : "service demand",
+ "schema" : {
+ "$ref" : "#/definitions/Demand"
+ }
+ } ],
+ "responses" : {
+ "201" : {
+ "description" : "plan created",
+ "schema" : {
+ "items" : {
+ "$ref" : "#/definitions/Plan"
+ }
+ }
+ },
+ "400" : {
+ "description" : "bad request",
+ "schema" : {
+ "$ref" : "#/definitions/Error"
+ }
+ },
+ "401" : {
+ "description" : "unauthorized request"
+ }
+ }
+ }
+ },
+ "/v1/plans/{plan_id}" : {
+ "get" : {
+ "summary" : "retreive a plan",
+ "operationId" : "getPlan",
+ "description" : "retrieve a plan",
+ "produces" : [ "application/json" ],
+ "parameters" : [ {
+ "in" : "path",
+ "name" : "plan_id",
+ "description" : "UUID of plan identifier",
+ "required" : true,
+ "type" : "string",
+ "format" : "uuid"
+ } ],
+ "responses" : {
+ "200" : {
+ "description" : "retrieve a plan",
+ "schema" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/Plan"
+ }
+ }
+ },
+ "400" : {
+ "description" : "bad request",
+ "schema" : {
+ "$ref" : "#/definitions/Error"
+ }
+ },
+ "401" : {
+ "description" : "unauthorized request"
+ },
+ "500" : {
+ "description" : "Internal Server Error"
+ }
+ }
+ },
+ "delete" : {
+ "summary" : "delete a plan",
+ "operationId" : "deletePlan",
+ "description" : "delete a plan",
+ "produces" : [ "application/json" ],
+ "parameters" : [ {
+ "in" : "path",
+ "name" : "plan_id",
+ "description" : "UUID of plan identifier",
+ "required" : true,
+ "type" : "string",
+ "format" : "uuid"
+ } ],
+ "responses" : {
+ "204" : {
+ "description" : "deleted a plan"
+ },
+ "400" : {
+ "description" : "bad request",
+ "schema" : {
+ "$ref" : "#/definitions/Error"
+ }
+ },
+ "401" : {
+ "description" : "unauthorized request"
+ }
+ }
+ }
+ }
+ },
+ "definitions" : {
+ "Demand" : {
+ "type" : "object",
+ "required" : [ "transaction_id", "template" ],
+ "properties" : {
+ "name" : {
+ "type" : "string"
+ },
+ "id" : {
+ "type" : "string",
+ "format" : "uuid"
+ },
+ "transaction_id" : {
+ "type" : "string",
+ "format" : "uuid",
+ "example" : "d290f1ee-6c54-4b01-90e6-d701748f0851"
+ },
+ "template" : {
+ "type" : "string",
+ "externalDocs" : {
+ "description" : "See here for template format",
+ "url" : "http://onap.readthedocs.io/en/latest/submodules/optf/has.git/docs/sections/homingspecification.html"
+ }
+ }
+ }
+ },
+ "Plan" : {
+ "type" : "object",
+ "required" : [ "plan", "id", "transaction_id", "name", "status", "message", "links", "recommendations" ],
+ "properties" : {
+ "plan" : {
+ "type" : "string",
+ "example" : "JSON string describing plan",
+ "externalDocs" : {
+ "description" : "See here for plan format",
+ "url" : "http://onap.readthedocs.io/en/latest/submodules/optf/has.git/docs/sections/offeredapis.html"
+ }
+ },
+ "id" : {
+ "type" : "string",
+ "format" : "uuid",
+ "example" : "d290f1ee-6c54-4b01-90e6-d701748f0851"
+ },
+ "transaction_id" : {
+ "type" : "string",
+ "format" : "uuid",
+ "example" : "d290f1ee-6c54-4b01-90e6-d701748f0851"
+ },
+ "name" : {
+ "type" : "string",
+ "example" : "name of plan"
+ },
+ "status" : {
+ "type" : "string",
+ "enum" : [ "template", "translated", "solving", "solved", "not found", "error" ]
+ },
+ "message" : {
+ "type" : "string",
+ "example" : "Additional context, if any, around the message status"
+ },
+ "links" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/Link"
+ },
+ "externalDocs" : {
+ "description" : "See here for links description",
+ "url" : "http://onap.readthedocs.io/en/latest/submodules/optf/has.git/docs/sections/offeredapis.html"
+ }
+ },
+ "recommendations" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/Recommendation"
+ },
+ "externalDocs" : {
+ "description" : "Refer to the Demand candidate schema in the Homing Template Guide for further details",
+ "url" : "http://onap.readthedocs.io/en/latest/submodules/optf/has.git/docs/sections/homingspecification.html"
+ }
+ }
+ }
+ },
+ "Link" : {
+ "required" : [ "href", "rel" ],
+ "properties" : {
+ "href" : {
+ "type" : "string",
+ "example" : "http://localhost:8091/v1"
+ },
+ "rel" : {
+ "type" : "string",
+ "example" : "self"
+ }
+ }
+ },
+ "Recommendation" : {
+ "required" : [ "recommendation" ],
+ "properties" : {
+ "recommendation" : {
+ "type" : "string",
+ "description" : "JSON string, see description of Plan.recommendations",
+ "example" : "JSON string describing recommendation"
+ }
+ }
+ },
+ "MediaTypes" : {
+ "required" : [ "base", "type" ],
+ "properties" : {
+ "base" : {
+ "type" : "string",
+ "example" : "application/json"
+ },
+ "rel" : {
+ "type" : "string",
+ "example" : "application/vnd.onap.has-v1+json"
+ }
+ }
+ },
+ "Versions" : {
+ "required" : [ "name", "links", "media_types", "status", "updated" ],
+ "properties" : {
+ "id" : {
+ "type" : "string",
+ "example" : "v1"
+ },
+ "links" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/Link"
+ }
+ },
+ "media-types" : {
+ "type" : "array",
+ "items" : {
+ "$ref" : "#/definitions/MediaTypes"
+ }
+ },
+ "status" : {
+ "type" : "string",
+ "example" : "EXPERIMENTAL"
+ },
+ "updated" : {
+ "type" : "string",
+ "example" : "2016-11-01T00:00:00Z"
+ }
+ }
+ },
+ "Error" : {
+ "properties" : {
+ "title" : {
+ "type" : "string",
+ "example" : "Bad Request"
+ },
+ "explanation" : {
+ "type" : "string",
+ "example" : "pl an did not pass validation against callable"
+ },
+ "code" : {
+ "type" : "integer",
+ "example" : 400
+ },
+ "error" : {
+ "properties" : {
+ "message" : {
+ "type" : "string",
+ "example" : "message"
+ },
+ "traceback" : {
+ "type" : "string",
+ "example" : "traceback"
+ },
+ "errortype" : {
+ "type" : "string",
+ "example" : "type"
+ }
+ }
+ }
+ }
+ }
+ },
+ "schemes" : [ "https" ],
+ "host" : "virtserver.swaggerhub.com",
+ "basePath" : "/onap_oof/has/1.0.0"
+} \ No newline at end of file