+============================================
ONAP Application Controller (APPC) API Guide
============================================
This document is intended for an advanced technical audience, such as the engineers or architects who need to use this guide to develop an interfacing application. The guide assumes a knowledge of the Open Network Automation Platform (ONAP) components and features, and familiarity with JSON notation.
-Conventions
------------
-
-+--------------+------------------------------------------------------------------------------------------+
-| Convention | Description |
-| | |
-+==============+==========================================================================================+
-|``Monospace`` | This font indicates sample codes, screenshots, or elements. For example:: |
-| | |
-| | "contact": { |
-| | "contactType": "USER", |
-| | "source": "app1", |
-| | } |
-| | |
-+--------------+------------------------------------------------------------------------------------------+
-|*Italics* | Emphasizes a point or denotes new terms at the place where they are defined in the text. |
-| | Indicates an external book title reference. |
-| | |
-+--------------+------------------------------------------------------------------------------------------+
-
-
-
Life Cycle Management Commands
==============================
For more details, see the APPC Client Library Guide at:
- guides/appc_api_client
+ :ref:`appc_client_library`
The client library supports both synchronous and asynchronous flows as follows.
-Asynchronous Flow
-^^^^^^^^^^^^^^^^^
+**Asynchronous Flow**
- The APPC Client Library is called via an asynchronous API using a full command object, which is mapped to a JSON representation.
- The APPC client calls the UEB/DMaaP client and sends the JSON command to a configured topic.
- The APPC client pulls response messages from the configured topic.
- On receiving the response for the command, APPC client runs the relevant callback method of the consumer ResponseHandler.
-Synchronous Flow
-^^^^^^^^^^^^^^^^
+**Synchronous Flow**
- The APPC Client Library is called via a synchronous API using a full command object, which is mapped to a JSON representation.
- The APPC client calls the UEB/DMaaP client and sends the JSON command to a configured topic.
The LCM API general request format is applicable for both POST HTTP API and for the message body received via the EUB/DMaaP bus.
LCM Request
-^^^^^^^^^^^
+-----------
The LCM request comprises a common header and a section containing the details of the LCM action.
The LCM request conforms to the following structure::
LCM Response
-^^^^^^^^^^^^
+------------
The LCM response comprises a common header and a section containing the payload and action details.
Status Codes
-^^^^^^^^^^^^
+------------
The status code is returned in the response message as the code parameter, and the description as the message parameter.
Malformed Message Response
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
A malformed message is an invalid request based on the LCM API YANG scheme specification. APPC rejects malformed requests as implemented by ODL infrastructure level.
artifacts to SDC which distributes them to all APPC instances in the
same environment (e.g., production).
-For more details, see the APPC Self-Service VNF Onboarding Guide (add link).
+For more details, see the APPC Self-Service VNF Onboarding Guide.
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+----------------------------------+
Audit Response
-^^^^^^^^^^^^^^
+--------------
The audit response returns an indication of success or failure of the audit. If a new configuration is uploaded to the APPC database, the payload contains the ‘upload\_config\_id’ and values for any records created. In addition, the configuration is sent to the ECOMP Data Router bus which may be received by an external configuration storage system.
+------------------------------+--------------------------------------------------------+
CheckLock Response
-^^^^^^^^^^^^^^^^^^
+------------------
The CheckLock command returns a customized version of the LCM
response.
Configure Response
-^^^^^^^^^^^^^^^^^^
+------------------
The Configure response returns an indication of success or failure of the request. If successful, the return payload contains the ‘upload\_config\_id’ and values for any records created. In addition, the configuration is sent to the ECOMP Data Router bus which may be received by an external configuration storage system.
A failed Configure action returns a failure response and the specific failure message in the response block.
ConfigModify Response
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
The ConfigModify response returns an indication of success or failure of the request. If successful, the return payload contains the ‘upload\_config\_id’ and values for any records created. In addition, the configuration is sent to the ECOMP Data Router bus which may be received by an external configuration storage system.
+---------------------+-------------------------------------------------------------------------+---------------------+------------------------------------+
Snapshot Response
-^^^^^^^^^^^^^^^^^
+-----------------
The Snapshot command returns an extended version of the LCM response.
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+
StartApplication Response
-^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------
The StartApplication response returns an indication of success or failure of the request.
+---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+-----------------------------------------------------------------+
StopApplication Response
-^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------
The StopApplication response returns an indication of success or failure of the request.
-NAP Application Controller (APPC) Client Library Guide
+.. _appc_client_library:
-+-----------------+------------------+
-+-----------------+------------------+
-| Revision | Version 1.0.0 |
-+-----------------+------------------+
-| Revision Date | 22 August 2017 |
-+-----------------+------------------+
+==================================================
+Application Controller (APPC) Client Library Guide
+==================================================
+
+
+Revision History
+----------------
+--------------+------------+---------------+--------------------------------------------------+
| Date | Revision | Author | Changes |
+--------------+------------+---------------+--------------------------------------------------+
-| 2017-08-22 | 1.0.0 | Paul Miller | First draft consistent with AT&T Release 17.10 |
+| 2017-08-22 | 1.0.0 | Paul Miller | First draft |
+--------------+------------+---------------+--------------------------------------------------+
+--------------+------------+---------------+--------------------------------------------------+
-|
-
-
-1. .. rubric:: Introduction
- :name: introduction
+Introduction
+============
- 1. .. rubric:: Target Audience
- :name: target-audience
+Target Audience
+---------------
- This document is for an advanced technical audience, which includes
- engineers and technicians. Document revisions occur with the release
- of new software versions.
+This document is for an advanced technical audience, which includes engineers and technicians. Document revisions occur with the release of new software versions.
Related Documentation
---------------------
- For additional information, see the ONAP Application Controller
- (APPC) API Guide.
-
- The following sections describe the conventions this document uses,
- including notices, text conventions, and command-line conventions.
-
-Command-line Conventions
-========================
-
-The following table lists possible elements in a command-line path.
-
-+------------------+--------------------------------------------------------------------------------------------------------+
-| **Convention** | **Description** |
-+==================+========================================================================================================+
-| Brackets [ ] | This is used for optional items. |
-+------------------+--------------------------------------------------------------------------------------------------------+
-| Braces { } | This indicates choices separated by pipe (\|) for sets from which only one is selected. For example: |
-| | |
-| | {even\|odd} |
-+------------------+--------------------------------------------------------------------------------------------------------+
-| Blue text | This indicates a link in this document online. |
-+------------------+--------------------------------------------------------------------------------------------------------+
-
-Text Conventions
-~~~~~~~~~~~~~~~~
-
- The following table lists text conventions in this document.
-
-+------------------------------------+----------------------------------------------------------------------------+
-| **Convention** | **Description** |
-+====================================+============================================================================+
-| Monospace font with blue shading | This font indicates sample codes, screenshots, or elements. For example: |
-| | |
-| | contact": { |
-| | |
-| | "contactType": "USER", |
-| | "source": "appl", |
-| | |
-| | } |
-+------------------------------------+----------------------------------------------------------------------------+
-| *Italics* | Emphasizes a point or denotes new terms defined in the text. |
-| | |
-| | Indicates an external book title reference. |
-+------------------------------------+----------------------------------------------------------------------------+
-| Numeric | A number composed of digits 0 through 9. |
-+------------------------------------+----------------------------------------------------------------------------+
-| Text | Any combination of alphanumeric characters. |
-| | |
-| | New items in RED |
-+------------------------------------+----------------------------------------------------------------------------+
-
-Authors and Contributors
-------------------------
+For additional information, see the ONAP Application Controller (APPC) API Guide.
- The following table lists the persons who are authors and
- contributors to this document.
-
-+--------------------+----------------------+
-| **Contributors** | |
-+====================+======================+
-| Borislav Glozman | Margrethe Fossberg |
-+--------------------+----------------------+
-| Paul Mellor | John Buja |
-+--------------------+----------------------+
-+--------------------+----------------------+
-
-Terms and Acronyms
-------------------
-
-The following table defines terms and acronyms used in this document.
-
-+-----------------------+--------------------------------------------------------------+
-| **Term or Acronym** | **Definition** |
-+=======================+==============================================================+
-| AAI | Active and Available Inventory |
-+-----------------------+--------------------------------------------------------------+
-| AAF | Authentication & Authorization Framework |
-+-----------------------+--------------------------------------------------------------+
-| AJSC | AT&T Java Service Container |
-+-----------------------+--------------------------------------------------------------+
-| API | Application Programming Interface |
-+-----------------------+--------------------------------------------------------------+
-| APPC | Application Controller |
-+-----------------------+--------------------------------------------------------------+
-| SDC | Service Design and Creation |
-+-----------------------+--------------------------------------------------------------+
-| DCAE | Data Collection Analytics and Events |
-+-----------------------+--------------------------------------------------------------+
-| DG | Directed Graph |
-+-----------------------+--------------------------------------------------------------+
-| DNS | Domain Name System |
-+-----------------------+--------------------------------------------------------------+
-| EELF | Event and Error Logging Framework |
-+-----------------------+--------------------------------------------------------------+
-| HDFS | Hadoop Distributed File System |
-+-----------------------+--------------------------------------------------------------+
-| HTTP | Hypertext Transfer Protocol |
-+-----------------------+--------------------------------------------------------------+
-| IAAS | Infrastructure As A Service |
-+-----------------------+--------------------------------------------------------------+
-| I/O | Input/Output |
-+-----------------------+--------------------------------------------------------------+
-| JMS | Java Messaging Service |
-+-----------------------+--------------------------------------------------------------+
-| JSON | JavaScript Object Notation |
-+-----------------------+--------------------------------------------------------------+
-| LAN | Local Area Network |
-+-----------------------+--------------------------------------------------------------+
-| LRM | Local Resource Monitor |
-+-----------------------+--------------------------------------------------------------+
-| SO | Service Orchestrator |
-+-----------------------+--------------------------------------------------------------+
-| NOD | Network on Demand |
-+-----------------------+--------------------------------------------------------------+
-| ODL | OpenDaylight |
-+-----------------------+--------------------------------------------------------------+
-| ONAP | Open Network Application Platform |
-+-----------------------+--------------------------------------------------------------+
-| OS | Operating System |
-+-----------------------+--------------------------------------------------------------+
-| PO | Platform Orchestrator |
-+-----------------------+--------------------------------------------------------------+
-| RCT | Reference Connection Tool |
-+-----------------------+--------------------------------------------------------------+
-| RO | Resource Orchestrator |
-+-----------------------+--------------------------------------------------------------+
-| SDN-C | Software Defined Network - Controller |
-+-----------------------+--------------------------------------------------------------+
-| SDN-GP | Software Defined Network - Global Platform |
-+-----------------------+--------------------------------------------------------------+
-| SME | Subject Matter Expert |
-+-----------------------+--------------------------------------------------------------+
-| SNMP | Simple Network Management Protocol |
-+-----------------------+--------------------------------------------------------------+
-| SMTP | Simple Mail Transfer Protocol |
-+-----------------------+--------------------------------------------------------------+
-| SOT | Source Of Truth (ext. system where data object originates) |
-+-----------------------+--------------------------------------------------------------+
-| SSH | Secure Shell |
-+-----------------------+--------------------------------------------------------------+
-| TCP | Transmission Control Protocol |
-+-----------------------+--------------------------------------------------------------+
-| TPS | Transactions per Second |
-+-----------------------+--------------------------------------------------------------+
-| UEB | Universal Event Broker |
-+-----------------------+--------------------------------------------------------------+
-| vCE | virtual CE (Customer Edge) router |
-+-----------------------+--------------------------------------------------------------+
-| vPE | virtual PE (Provider Edge) router |
-+-----------------------+--------------------------------------------------------------+
-| VLAN | Virtual Local Area Network |
-+-----------------------+--------------------------------------------------------------+
-| VM | Virtual Machine |
-+-----------------------+--------------------------------------------------------------+
-| VNF | Virtual Network Function |
-+-----------------------+--------------------------------------------------------------+
-| VNFC | Virtual Network Function Component |
-+-----------------------+--------------------------------------------------------------+
-| vSCP | Virtualized Service Control Point |
-+-----------------------+--------------------------------------------------------------+
-| WAN | Wide Area Network |
-+-----------------------+--------------------------------------------------------------+
-| WUI | Web User Interface |
-+-----------------------+--------------------------------------------------------------+
-| XML | Extensible Markup Language |
-+-----------------------+--------------------------------------------------------------+
-| YAML | YAML Ain't Markup Language |
-+-----------------------+--------------------------------------------------------------+
Client Library Background
--------------------------
+=========================
- This guide discusses the Application Controller (APPC) Client
- Library and how to use it.
+This guide discusses the Application Controller (APPC) Client Library and how to use it.
About the Client Library
------------------------
- The APPC client library provides consumers of APPC capabilities with
- a strongly-typed Java interface and encapsulates the actual
- interaction with the APPC component over an asynchronous messaging
- channel such as UEB.
+The APPC client library provides consumers of APPC capabilities with a strongly-typed Java interface and encapsulates the actual interaction with the APPC component over an asynchronous messaging channel such as UEB.
Consumer Logic
--------------
- The client application that consumes APPC's capability for VNF
- lifecycle management (the APPC client library) can be implemented
- against the lightweight and strongly-typed Java API exposed by the
- APPC client library. The library does not try to impose
- architectural constraints upon clients, but instead provides support
- for different options and styles of API. It is the responsibility of
- the client application to select the most suitable paradigm to use;
- for example, a client may choose to use blocking calls as opposed to
- asynchronous notifications.
+The client application that consumes APPC’s capability for VNF lifecycle management (the APPC client library) can be implemented against the lightweight and strongly-typed Java API exposed by the APPC client library. The library does not try to impose architectural constraints upon clients, but instead provides support for different options and styles of API. It is the responsibility of the client application to select the most suitable paradigm to use; for example, a client may choose to use blocking calls as opposed to asynchronous notifications.
VNF Lifecycle Management API
----------------------------
- The API represents a relatively thin layer that consists mainly of
- business interfaces with strongly-typed APIs and a data object model
- created for the convenience of the consumer application.Â
-
- The original YANG schema used by the APPC component and the
- underlying MD-SAL layer on the server-side generates these
- artifacts.
+The API represents a relatively thin layer that consists mainly of business interfaces with strongly-typed APIs and a data object model created for the convenience of the consumer application. The original YANG schema used by the APPC component and the underlying MD-SAL layer on the server-side generates these artifacts.
APP-C Client Library Flow
-------------------------
|image0|
-Asynchronous Flow
------------------
-
-- The APPC Client Library is called using an asynchronous API using a
- full command object, which is mapped to a JSON representation.
-
-- The APPC client calls the UEB client and sends the JSON command to a
- configured topic.
+**Asynchronous Flow**
+- The APPC Client Library is called using an asynchronous API using a full command object, which is mapped to a JSON representation.
+- The APPC client calls the UEB client and sends the JSON command to a configured topic.
- The APPC client pulls response messages from the configured topic.
+- On receiving the response for the command, the APPC client runs the relevant callback method of the consumer ResponseHandler.
-- On receiving the response for the command, the APPC client runs the
- relevant callback method of the consumer ResponseHandler.
-
- 1. .. rubric:: Synchronous Flow
- :name: synchronous-flow
-
-- The APPC Client Library is called using a synchronous API using a
- full command object, which is mapped to a JSON representation.
-
-- The APPC client calls the UEB client and sends the JSON command to a
- configured topic.
+**Synchronous Flow**
+- The APPC Client Library is called using a synchronous API using a full command object, which is mapped to a JSON representation.
+- The APPC client calls the UEB client and sends the JSON command to a configured topic.
- The APPC client pulls response messages from the configured topic.
+- On receiving the **final** response for the command, the APPC client returns the response object with a final status.
-- On receiving the **final** response for the command, the APPC client
- returns the response object with a final status.
-
-1. .. rubric:: Client Library Usage
- :name: client-library-usage
-
- 1. .. rubric:: Jar Files
- :name: jar-files
+Client Library Usage
+====================
+
+Jar Files
+---------
- The Java application that runs the APPC client kit uses the
- following jar files:
+The Java application that runs the APPC client kit uses the following jar files:
-- com.att.appc.client.client-kit
+ - com.att.appc.client.client-kit
+ - com.att.appc.client.client-lib
-- com.att.appc.client.client-lib
+The client library JAR files are located in the repository under ``com\\att\\appc\\client``.
- The client library JAR files are located in the repository under
- /gerrit.onap.org/r/p/appc.git/appc-client.
-
-Initialization
+Initialization
--------------
- Initialize the client by calling the following method:
-
- AppcClientServiceFactoryProvider.getFactory(AppcLifeCycleManagerServiceFactory.class).createLifeCycleManagerStateful()
-
- Specify the following configuration properties as method parameters:
-
-- "topic.read"
-
-- "topic.read.timeout"
-
-- "topic.write"
-
-- "client.key"
+Initialize the client by calling the following method:
-- "client.secret"
+``AppcClientServiceFactoryProvider.getFactory(AppcLifeCycleManagerServiceFactory.class).createLifeCycleManagerStateful()``
-- "client.name"
+Specify the following configuration properties as method parameters:
-- "client.name.id"
-
-- "poolMembers"
-
-- "client.response.timeout"
-
-- "client.graceful.shutdown.timeout"
+ - "topic.read"
+ - "topic.read.timeout"
+ - "topic.write"
+ - "client.key"
+ - "client.secret"
+ - "client.name"
+ - "client.name.id"
+ - "poolMembers"
+ - “client.response.timeout”
+ - “client.graceful.shutdown.timeout”
Shutdown
--------
Shutdown the client by calling the following method:
-void shutdownLifeCycleManager(boolean isForceShutdown)
+``void shutdownLifeCycleManager(boolean isForceShutdown)``
-If the isForceShutdown flag is set to false, the client shuts down as
-soon as all responses for pending requests are received, or upon
-configurable timeout. (client.graceful.shutdown.timeout).
+If the ``isForceShutdown`` flag is set to false, the client shuts down as soon as all responses for pending requests are received, or upon configurable timeout. (``client.graceful.shutdown.timeout``).
-If the isForceShutdown flag is set to true, the client shuts down
-immediately.
+If the ``isForceShutdown`` flag is set to true, the client shuts down immediately.
Invoking LCM Commands
---------------------
Invoke the LCM commands by:
-- Creating input objects, such as AuditInput, LiveUpgradeInput, with
- relevant command information.
-
-- Executing commands asynchronously, for example:
+ - Creating input objects, such as AuditInput, LiveUpgradeInput, with relevant command information.
+ - Executing commands asynchronously, for example:
-void liveUpgrade(LiveUpgradeInput liveUpgradeInput,
-ResponseHandler<LiveUpgradeOutput> listener) throws
-AppcClientException;)
+``void liveUpgrade(LiveUpgradeInput liveUpgradeInput, ResponseHandler<LiveUpgradeOutput> listener) throws AppcClientException;)``
In this case, client should implement the ResponseHandler<T> interface.
-- Executing commands synchronously, for example:
+ - Executing commands synchronously, for example:
+
+``LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws AppcClientException;)``
-LiveUpgradeOutput liveUpgrade(LiveUpgradeInput liveUpgradeInput) throws
-AppcClientException;)
Client API
-----------
+==========
- After initializing the client, a returned Object of type
- LifeCycleManagerStateful defines all the Life Cycle Management APIs
- supported by APPC.
+After initializing the client, a returned Object of type LifeCycleManagerStateful defines all the Life Cycle Management APIs
+ supported by APPC.
- The interface contains two definitions for each RPC: one for
- Asynchronous call mode, and one for Synchronous.
+The interface contains two definitions for each RPC: one for Asynchronous call mode, and one for Synchronous.
- In Asynchronous mode, client consumer should provide a callback
- function of type:
+In Asynchronous mode, client consumer should provide a callback function of type:
- ResponseHandler<RPC-NAMEOutput>
+ ``ResponseHandler<RPC-NAMEOutput>``
- where RPC-NAME is the command name, such as Audit or Snapshot.
+where ``RPC-NAME`` is the command name, such as Audit or Snapshot.
- There may be multiple calls to the ResponseHandler for each response
- returned by APPC. For example, first 100 'accept' is returned, then
- 400 'success'.
+There may be multiple calls to the ResponseHandler for each response returned by APPC. For example, first 100 ‘accept’ is returned, then 400 ‘success’.
LifeCycleManagerStateful Interface
----------------------------------
- Generated from the APPC Yang model, this interface defines the
- services and request/response requirements for the ECOMP APPC
- component. For example, for LCM Command Audit, the following is
- defined:
+Generated from the APPC Yang model, this interface defines the services and request/response requirements for the ECOMP APPC component. For example, for LCM Command Audit, the following is defined:
- @RPC(name="audit", outputType=AuditOutput.class)
+``@RPC(name="audit", outputType=AuditOutput.class)``
- AuditOutput audit(AuditInput auditInput) throws AppcClientException;
+``AuditOutput audit(AuditInput auditInput) throws AppcClientException;``
- For a Synchronous call to Audit, the consumer thread is blocked
- until a response is received or a timeout exception is thrown.
+For a Synchronous call to Audit, the consumer thread is blocked until a response is received or a timeout exception is thrown.
- @RPC(name="audit", outputType=AuditOutput.class)
+``@RPC(name="audit", outputType=AuditOutput.class)``
- void audit(AuditInput auditInput, ResponseHandler<AuditOutput>
- listener) throws AppcClientException;
+``void audit(AuditInput auditInput, ResponseHandler<AuditOutput> listener) throws AppcClientException;``
- For an Asynchronous call to Audit, a callback should be provided so
- that when a response is received the listener is called.
+For an Asynchronous call to Audit, a callback should be provided so that when a response is received the listener is called.
API documentation
-----------------
- The API documentation is also available as a swagger page generated
- from files at /client-kit/target/resources.
+The API documentation is also available as a swagger page generated from files at /client-kit/target/resources.
appc-provider-lcm
-----------------
-This defines the services and request/response requirements for the APPC
-component.
+This defines the services and request/response requirements for the APPC component.
-Methods
+Methods
--------
-The methods should match the actions described in the LCM API Guide. For
-each method:
+The methods should match the actions described in the LCM API Guide. For each method:
**Consumes**
-This API call consumes the following media types using the
-**Content-Type** request header:
+This API call consumes the following media types using the**Content-Type** request header:
-- application/json
+ - ``application/json``
**Request body**
**Return type**
-The return type is the action name followed by Output (e.g.,
-OutputInput)
+The return type is the action name followed by Output (e.g., OutputInput)
**Produces**
-This API call produces the following media types according to the
-**Accept** request header; the **Content-Type** response header conveys
-the media type.
+This API call produces the following media types according to the **Accept** request header; the **Content-Type** response header conveys the media type.
-- application/json
+ - ``application/json``
**Responses**
.. |image0| image:: image2.png
:width: 5.60495in
:height: 4.55272in
-
-
Code Review / appc.git / commitdiff