From: Ankitkumar Patel Date: Tue, 13 Feb 2018 06:31:05 +0000 (-0500) Subject: Added SO-OOF/HAS API document X-Git-Url: https://gerrit.onap.org/r/gitweb?p=optf%2Fosdf.git;a=commitdiff_plain;h=0532bd48bb683bbdb16bf73e4ac9e9ba74ba4f20 Added SO-OOF/HAS API document Created the docs folder and added SO-OOF/HAS API document. Issue-ID: OPTFRA-62 Change-Id: I7145bc134a13eade5819758605be9077d295f921 Signed-off-by: Ankitkumar Patel --- diff --git a/docs/apis/OOF_HAS_R2_Interface.rst b/docs/apis/OOF_HAS_R2_Interface.rst new file mode 100644 index 0000000..2e26945 --- /dev/null +++ b/docs/apis/OOF_HAS_R2_Interface.rst @@ -0,0 +1,316 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +OOF-HAS Beijing Interfaces +========================== + +OOF-HAS APIs +============ + +Create/Update a homing optimization service instance +++++++++++++++++++++++++++++++++++++++++++++++++++++ + ++--------------------+-------------------------------------+ +|Interface Definition|Description | ++====================+=====================================+ +|URI |{serverRoot}/oof/has/v2 | ++--------------------+-------------------------------------+ +|Operation Type |POST | ++--------------------+-------------------------------------+ +|Content-Type |application/json | ++--------------------+-------------------------------------+ + + +Request Headers: + ++----------------+-----------+-------------------------------------------------------------------------------------------+ +| Header Name | Qualifier | Description | ++================+===========+===========================================================================================+ +| Accept | N | Determines the format of the body of the response. Valid value is “application/json” | ++----------------+-----------+-------------------------------------------------------------------------------------------+ +| Authorization | Y | Supplies Basic Authentication credentials for the request. If the Authorization header is | +| | | missing, then an HTTP 400 Invalid Request response is returned. If the string supplied is | +| | | invalid, then an HTTP 401 Unauthorized response is returned. | ++----------------+-----------+-------------------------------------------------------------------------------------------+ +| Content-Type | Y | Determines the format of the request content. Only application/json is supported. | ++----------------+-----------+-------------------------------------------------------------------------------------------+ +| Content-Length | N | Number of bytes in the body of the request. Note that content length is limited to 1 MB. | ++----------------+-----------+-------------------------------------------------------------------------------------------+ + + +Request Body: + ++---------------+-----------+-------------+----------------------+---------------+------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===============+===========+=============+======================+===============+==========================================+ +| requestInfo | M | 1 | RequestInfo Object | - | The content of the RequestInfo object. | ++---------------+-----------+-------------+----------------------+---------------+------------------------------------------+ +| placementInfo | M | 1 | PlacementInfo Object | - | The Content of the PlacementInfo object. | ++---------------+-----------+-------------+----------------------+---------------+------------------------------------------+ +| licenseInfo | M | 1 | LicenseInfo Object | - | The Content of the LicenseInfo object. | ++---------------+-----------+-------------+----------------------+---------------+------------------------------------------+ +| serviceInfo | M | 1 | ServiceInfo Object | - | The Content of the ServiceInfo object. | ++---------------+-----------+-------------+----------------------+---------------+------------------------------------------+ + + +RequestInfo Object: + ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===============+===========+=============+=================+===============+=======================================================================+ +| transactionId | M | 1 | UUID/String | - | A unique ID to track an ONAP transaction. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| requestId | M | 1 | UUID/String | - | A unique ID to track multiple requests associated with a transaction. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| callbackUrl | M | 1 | URL | - | The end point of a callback service where recommendations are posted. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| sourceId | M | 1 | String | - | The unique ID of a client making an optimization call. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| requestType | M | 1 | String | create, | The type of a request | +| | | | | update, | | +| | | | | delete | | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| numSolutions | O | 1 | Integer | - | Expected number of solutions. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| optimizers | M | 1..N | List of Strings | placement | A list of optimization services. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ +| timeout | M | 1 | Integer | - | A tolerance window (in min) for expecting solutions. | ++---------------+-----------+-------------+-----------------+---------------+-----------------------------------------------------------------------+ + + +PlacementInfo Object: + ++-------------------+-----------+-------------+--------------------------------+---------------+---------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===================+===========+=============+================================+===============+===================================================+ +| requestParameters | M | 1 | JSON BLOB | - | A service ordering information. | ++-------------------+-----------+-------------+--------------------------------+---------------+---------------------------------------------------+ +| placementDemands | M | 1..N | List of PlacementDemand Object | - | The resource information for a placement service. | ++-------------------+-----------+-------------+--------------------------------+---------------+---------------------------------------------------+ + + +PlacementDemand Object: + ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++====================+===========+=============+======================+===============+=================================================================+ +| resourceModuleName | M | 1 | String | - | A resource name as defined in a service model. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| serviceResourceId | M | 1 | String | - | A unique resource Id with a local scope between client and OOF. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| tenantId | O | 1 | String | - | A tenant Id as defined in the ordering system. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| resourceModelInfo | M | 1 | ModelMetaData Object | - | Resource model information as defined in SDC. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| existingCandidates | O | 1 | Candidates Object | - | The existing placement information of a resource. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| excludedCandidates | O | 1 | Candidates Object | - | Candidates that need to be excluded from solutions. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| requiredCandidates | O | 1 | Candidates Object | - | Candidates that must be included in solutions. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ + + +ModelMetaData Object: + ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++========================+===========+=============+=========+===============+===========================================================+ +| modelInvariantId | M | 1 | String | - | A model invariant Id as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| modelVersionId | M | 1 | String | - | A unique model Id as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| modelName | O | 1 | String | - | A model name as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| modelType | O | 1 | String | - | A model type as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| modelVersion | O | 1 | String | - | A model version as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ +| modelCustomizationName | O | 1 | String | - | A model customization name as defined in a service model. | ++------------------------+-----------+-------------+---------+---------------+-----------------------------------------------------------+ + + +Candidates Object: + ++----------------+-----------+-------------+-----------------+----------------------+--------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++================+===========+=============+=================+======================+==========================+ +| identifierType | M | 1 | String | service_instance_id, | The type of a candidate. | +| | | | | vnf_name, | | +| | | | | cloud_region_id | | ++----------------+-----------+-------------+-----------------+----------------------+--------------------------+ +| identifiers | M | 1..N | List of Strings | - | A list of identifiers. | ++----------------+-----------+-------------+-----------------+----------------------+--------------------------+ + + +ServiceInfo Object: + ++-------------------+-----------+-------------+----------------------+---------------+--------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===================+===========+=============+======================+===============+==================================================+ +| serviceInstanceId | M | 1 | String | - | A service instance id associated with a request. | ++-------------------+-----------+-------------+----------------------+---------------+--------------------------------------------------+ +| serviceModelInfo | M | 1 | ModelMetaData Object | - | A list of identifiers. | ++-------------------+-----------+-------------+----------------------+---------------+--------------------------------------------------+ + + +LicenseInfo Object: + ++----------------+-----------+-------------+-------------------------------+---------------+--------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++================+===========+=============+===============================+===============+============================================+ +| licenseDemands | M | 1 | List of LicenseDemands Object | - | A list of resources for license selection. | ++----------------+-----------+-------------+-------------------------------+---------------+--------------------------------------------+ + + +LicenseDemands Object: + ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++====================+===========+=============+======================+===============+=================================================================+ +| resourceModuleName | M | 1 | String | - | A resource name as defined in a service model. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| serviceResourceId | M | 1 | String | - | A unique resource Id with a local scope between client and OOF. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| resourceModelInfo | M | 1 | ModelMetaData Object | - | Resource model information as defined in a service model. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ +| existingLicenses | O | 1 | LicenseModel Object | - | Existing license information assigned to a resource. | ++--------------------+-----------+-------------+----------------------+---------------+-----------------------------------------------------------------+ + + +LicenseModel Object: + ++---------------------+-----------+-------------+-----------------+---------------+----------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++=====================+===========+=============+=================+===============+====================================================+ +| entitlementPoolUUID | M | 1..N | List of Strings | - | Entitlement pool UUIDs associated with a resoruce. | ++---------------------+-----------+-------------+-----------------+---------------+----------------------------------------------------+ +| licenseKeyGroupUUID | M | 1..N | List of Strings | - | License key groups associated with a resource | ++---------------------+-----------+-------------+-----------------+---------------+----------------------------------------------------+ + + +Synchronous Response Body: + ++---------------+-----------+-------------+-------------+------------------+------------------------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===============+===========+=============+=============+==================+========================================================================+ +| requestId | M | 1 | UUID/String | - | A unique Id for an ONAP transaction. | ++---------------+-----------+-------------+-------------+------------------+------------------------------------------------------------------------+ +| transactionId | M | 1 | UUID/String | - | A unique ID to tranck multiple requests associated with a transaction. | ++---------------+-----------+-------------+-------------+------------------+------------------------------------------------------------------------+ +| statusMessage | O | 1 | String | - | Reasoning if a requestStatus is failure. | ++---------------+-----------+-------------+-------------+------------------+------------------------------------------------------------------------+ +| requestStatus | M | 1 | String | success, failure | The status of a request. | ++---------------+-----------+-------------+-------------+------------------+------------------------------------------------------------------------+ + + +Asyncronous Response Body: + ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===============+===========+=============+=================+===============+========================================================================+ +| requestId | M | 1 | UUID/String | - | A unique Id for an ONAP transaction. | ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ +| transactionId | M | 1 | UUID/String | - | A unique ID to tranck multiple requests associated with a transaction. | ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ +| statusMessage | O | 1 | String | - | Reasoning if requestStatus is failure. | ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ +| requestStatus | M | 1 | String | success, | The status of a request. | +| | | | | failure, | | +| | | | | pending | | ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ +| solutions | M | 1 | Solution Object | - | Solutions related to a request. | ++---------------+-----------+-------------+-----------------+---------------+------------------------------------------------------------------------+ + + +Solutions Object: + ++--------------------+-----------+-------------+--------------------------------------+---------------+--------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++====================+===========+=============+======================================+===============+================================+ +| placementSolutions | M | 1..N | List of ComprehensiveSolution Object | - | A list of placement solutions. | ++--------------------+-----------+-------------+--------------------------------------+---------------+--------------------------------+ +| licenseSolutions | M | 1 | List of LicenseSolution Object | - | A list of license solutions | ++--------------------+-----------+-------------+--------------------------------------+---------------+--------------------------------+ + + + +ComprehensiveSolution Object: + ++-----------+-----------+-------------+----------------------------------+---------------+--------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===========+===========+=============+==================================+===============+================================+ +| - | M | 1..N | List of PlacementSolution Object | - | A list of placement solutions. | ++-----------+-----------+-------------+----------------------------------+---------------+--------------------------------+ + + +PlacementSolution Object: + ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++====================+===========+=============+========================+=====================+=========================================================+ +| resourceModuleName | M | 1 | String | - | The name of a resource as defined in the service model. | ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ +| serviceResourceId | M | 1 | String | - | A resource Id as defined in a service model. | ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ +| identifierType | M | 1 | String | service_instance_id | The type of a candidate. | ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ +| identifier | M | 1 | String | - | The id of a candidate. | ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ +| assignmentInfo | O | 1..N | List of AssignmentInfo | - | Additional information related to a candidate. | +| | | | object | | | ++--------------------+-----------+-------------+------------------------+---------------------+---------------------------------------------------------+ + + +AssignmentInfo Object: + ++-----------+-----------+-------------+---------+---------------+---------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++===========+===========+=============+=========+===============+=====================+ +| key | M | 1 | String | - | An attribute name. | ++-----------+-----------+-------------+---------+---------------+---------------------+ +| value | M | 1 | String | - | An attribute value. | ++-----------+-----------+-------------+---------+---------------+---------------------+ + + +LicenseSolutions Object: + ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| Attribute | Qualifier | Cardinality | Content | Domain Values | Description | ++==============================+===========+=============+================+===============+==========================================+ +| resourceModuleName | M | 1 | String | - | A resource name as defined in a service. | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| serviceResourceId | M | 1 | String | - | A resource Id as defined in a service. | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| entitlementPoolUUID | M | 1..N | List of String | - | A list of entitlementPoolUUIDs. | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| licenseKeyGroupUUID | M | 1..N | List of String | - | A list of licenseKeyGroupUUID. | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| entitlementPoolInvariantUUID | M | 1..N | List of String | - | A list of entitlementPoolInvariantUUID . | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ +| licenseKeyGroupInvariantUUID | M | 1..N | List of String | - | A list of licenseKeyGroupInvariantUUID . | ++------------------------------+-----------+-------------+----------------+---------------+------------------------------------------+ + + +HTTP Response Code +++++++++++++++++++ + ++-----------+-----------------------+---------------------------------------------------------------+ +| HTTP Code | Response Phrase | Description | ++===========+=======================+===============================================================+ +| 201 | Created | An optimization solution is found. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 202 | Accepted | An optimization reequest is accepted. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 400 | Bad request | Bad request. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 401 | Unauthorized | Request body is not compliant with the API definition. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 404 | Not found | The server cannot find the requested URI. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 405 | Method not found | The requested method is not supported by a server. | ++-----------+-----------------------+---------------------------------------------------------------+ +| 500 | Internal server error | The server encountered an internal server error or timed out. | ++-----------+-----------------------+---------------------------------------------------------------+ + + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..729167d --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,10 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Optimization Service Design Framework (OOF-OSDF) +================================================ + +.. toctree:: + :maxdepth: 4 + + apis/OOF_HAS_R2_Interface.rst + release-notes.rst diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..8eecdea --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,33 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Release Notes +============= + +Version: 0.1.0 +-------------- + + +:Release Date: YYYY-MM-DD + + +**New Features** + + +**Bug Fixes** + + +**Known Issues** + + +**Security Issues** + + +**Upgrade Notes** + + +**Deprecation Notes** + + +**Other** + +