Merge "Replace toscaparser with native yaml to load published Tosca file into memory"

[domino.git] / docs / userguide / api-documentation.rst

diff --git a/docs/userguide/api-documentation.rst b/docs/userguide/api-documentation.rst
index bd555de..166da6a 100755 (executable)
--- a/docs/userguide/api-documentation.rst
+++ b/docs/userguide/api-documentation.rst
@@ -9,11 +9,33 @@
 .. these two pipes are to seperate the logo from the first title
 |
 |
+Domino API and Usage
+====================
+
 Using domino-cli Client
-=======================
-Make sure that domino-cli.py is in +x mode.
+-----------------------
+
+Prerequisites:
+
+1. Make sure that domino-cli.py is in +x mode.
+
+2. Change directory to where domino-cli.py, DominoClient.py and DominoServer.py are located or include file path in the PATH environment variable.
+
+3. Start the Domino Server:
+
+.. code-block:: bash
+
+  ./DominoServer.py --log=debug
+
+4. Start the Domino Client:
+
+.. code-block:: bash
+
+  ./DominoClient.py -p <portnumber> --cliport <cli-portnumber> --log=debug
+
+Note1: The default log level is WARNING and omitting --log option will lead to minimal/no logging on the console
 
-Change directory to where domino-cli.py is located or include file path in the PATH environment variable.
+Note2: domino_conf.py file includes most of the default values
 
 * Registration Command
 
@@ -21,7 +43,7 @@ Command line input:
 
 .. code-block:: bash
 
-  ./domino-cli.py register
+  ./domino-cli.py <cli-portnumber> register
 
 This message has the following fields that are automatically filled in.
 
@@ -40,7 +62,7 @@ Command line input:
 
 .. code-block:: bash
 
-  ./domino-cli.py heartbeat
+  ./domino-cli.py <cli-portnumber> heartbeat
 
 This message has the following fields that are automatically filled in.
 
@@ -54,7 +76,7 @@ This message has the following fields that are automatically filled in.
 
 .. code-block:: bash
 
-  ./domino-cli.py subscribe -l <labelname> -t <templatetype>
+  ./domino-cli.py <cli-portnumber> subscribe -l <labelname> -t <templatetype>
 
 Note that -l can be substituted by --label and -t can be substituted by --ttype.
 
@@ -62,13 +84,13 @@ More than one label or template type can be subscribed within the same command l
 
 .. code-block:: bash
 
-  ./domino-cli.py subscribe -l <label1>,<label2>,<labeln> -t <ttype1>,<ttype2>,<ttypen>
+  ./domino-cli.py <cli-portnumber> subscribe -l <label1>,<label2>,<labeln> -t <ttype1>,<ttype2>,<ttypen>
 
 To subscribe more than one label or template type, one can also repeat the options -l and -t, e.g.:
 
 .. code-block:: bash
 
-  ./domino-cli.py subscribe -l <label1> -l <label2> -l <labeln> -t <ttype1> -t <ttype2> -t <ttypen>
+  ./domino-cli.py <cli-portnumber> subscribe -l <label1> -l <label2> -l <labeln> -t <ttype1> -t <ttype2> -t <ttypen>
 
 It is safe to call subscribe command multiple times with duplicate labels.
 
@@ -77,23 +99,35 @@ This message has the following fields that are automatically filled in.
 .. code-block:: bash
 
   Message Type (= SUBSCRIBE)
-  UDID (= Unique Domino IDassigned during registration)
+  UDID (= Unique Domino ID assigned during registration)
   Sequence Number (=incremented after each RPC call)
   Template Operation (= APPEND)
   Label Operation (= APPEND)
 
 The following fields are filled in based on arguments passed on via -l/--label and -t/--ttype flags
 
+Subscribe RPC also supports options for label using
+  --lop=APPEND/DELETE/OVERWRITE
+and for supported template types using
+  --top=APPEND/DELETE/OVERWRITE.
+When unspecified, the default is APPEND.
+DELETE deletes existing labels (template types) specified in the current call via key -l/--label (-t/--ttype).
+OVERWRITE removes the current set of labels (template types) and sets it to the new set of values passed in the same RPC call.
+
+By default, no translation service is provided. Currently, only TOSCA to Heat
+Orchestration Template (HOT) translation is supported using OpenStack
+heat-translator library. A domain that requires HOT files must subscribe HOT
+template type using
+
 .. code-block:: bash
 
-  Supported Template Types
-  Supported Labels
+  ./domino-cli.py <cli-portnumber> subscribe -t hot
 
 * Template Publishing Command
 
 .. code-block:: bash
 
-  ./domino-cli.py publish -t <toscafile>
+  ./domino-cli.py <cli-portnumber> publish -t <toscafile>
 
 Note that -t can be substituted by --tosca-file.
 
@@ -104,15 +138,31 @@ This message has the following fields that are automatically filled in.
 .. code-block:: bash
 
   Message Type (= SUBSCRIBE)
-  UDID (= Unique Domino IDassigned during registration)
+  UDID (= Unique Domino ID assigned during registration)
   Sequence Number (=incremented after each RPC call)
   Template Type (= TOSCA)
   Template File
 
+
 Interactive CLI mode
-====================
+--------------------
+
+To enter this mode, start Domino Client with interactive console option set as true, i.e., --iac=true:
+
+.. code-block:: bash
+
+  ./DominoClient -p <portnumber> --iax=true --log=DEBUG
+
+The rest of the API calls are the same as in the case of using domino-cli.py except that at the prompt there is no need to write "domino-cli.py <cli-portnumber>, e.g.,:
+
+.. code-block:: bash
 
+  >>register
+  >>heartbeat
+  >>subscribe -l <label1> -t <ttype1>
+  >>publish -t <toscafile>
 
+The interactive CLI mode is mainly supported for manual testing.
 
 Revision: _sha1_