diff options
| -rw-r--r-- | docs/sections/offeredapis.rst | 470 | ||||
| -rw-r--r-- | docs/sections/swaggerdoc/oof-has-api.json | 341 |
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 |