From 17b196f1326d6b6c249d44b8744d73d7bba12d7a Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Fri, 10 Jun 2016 13:49:34 +0200 Subject: [PATCH] Improves documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit The script updt.sh is revisited to generate better the meta data. The format of events is documented. Change-Id: I3bb7347f3ac0f660196a25a4c0c0432848fe4168 Signed-off-by: JosÃ© Bollo --- doc/FAQ.md | 1 - doc/README.html | 6 +++- doc/afb-application-writing.html | 75 ++++++++++++++++++++++++++++++++-------- doc/afb-application-writing.md | 66 ++++++++++++++++++++++++++++------- doc/afb-daemon-vocabulary.md | 2 +- doc/afb-overview.md | 2 +- doc/afb-plugin-writing.html | 6 ++-- doc/afb-plugin-writing.md | 4 +-- doc/afb-plugins-overview.html | 10 +++++- doc/afb-plugins-overview.md | 9 +++-- doc/afb-tests-overview.html | 6 ++-- doc/afb-tests-overview.md | 2 +- doc/updt.sh | 53 ++++++++++++++++++---------- 13 files changed, 181 insertions(+), 61 deletions(-) diff --git a/doc/FAQ.md b/doc/FAQ.md index 61105823..7dad1ab2 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -4,6 +4,5 @@ Frequently Asked Question about AFB-DAEMON Date: 27 mai 2016 Author: JosÃ© Bollo -TABLE-OF-CONTENT-HERE diff --git a/doc/README.html b/doc/README.html index a45c16e1..837505ae 100644 --- a/doc/README.html +++ b/doc/README.html @@ -4,7 +4,7 @@ - + ### Inititial Build +

HOWTO WRITE an APPLICATION above AGL FRAMEWORK

JosÃ© Bollo

Fulup Ar Foll

09 juin 2016

@@ -32,10 +53,16 @@

Example of session management

Format of replies

Template
Field jtype
Field request
Field response
Template

Format of events

Template
Field jtype
Field event
Field data

Using afb-client-demo

+
The program is packaged within AGL in the rpm libafbwsc-dev
+

Here is an example of exchange using afb-client-demo:

$ afb-client-demo ws://localhost:1234/api?token=123456
 auth connect
@@ -155,6 +185,19 @@ ON-REPLY 1:auth/check: {"jtype":"afb-reply","request&qu
 Format of replies
 Replies use javascript object returned as serialized JSON.
 This object contains at least 2 mandatory fields of name jtype and request and one optional field of name response.
+Template
+This is a template of replies:
+{
+   "jtype": "afb-reply",
+   "request": {
+      "status": "success",
+      "info": "informationnal text",
+      "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+      "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+      "reqid": "application-generated-id-23456"
+   },
+   "response": ....any response object....
+}
 Field jtype
 The field jtype must have a value of type string equal to "afb-reply".
 Field request
@@ -171,18 +214,22 @@ ON-REPLY 1:auth/check: {"jtype":"afb-reply","request&qu
 reqid is of type string. It is sent in response to HTTP requests that added a parameter of name reqid or x-afb-reqid at request time. Value returns in the reply has the exact same value as the one received in the request.
 Field response
 This field response optionally contains an object returned when request succeeded.
-Template
-This is a template of replies:
-{
-  "jtype": "afb-reply",
-  "request": {
-       "status": "success",
-       "info": "informationnal text",
-       "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
-       "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
-       "reqid": "application-generated-id-23456"
-     },
-  "response": ....any response object....
-}
+Format of events
+Events are javascript object serialized as JSON.
+This object contains at least 2 mandatory fields of name jtype and event and one optional field of name data.
+Template
+Here is a template of event:
+{
+   "jtype": "afb-event",
+   "event": "sample_api_name/sample_event_name",
+   "data": ...any event data...
+}
+Field jtype
+The field jtype must have a value of type string equal to "afb-event".
+Field event
+The field event carries the event's name.
+The name of the event is made of two parts separated by a slash: the name of the name of the API that generated the event and the name of event within the API.
+Field data
+This field data if present holds the data carried by the event.
 
 
diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md
index 1fd02e5f..772d9914 100644
--- a/doc/afb-application-writing.md
+++ b/doc/afb-application-writing.md
@@ -4,7 +4,7 @@ HOWTO WRITE an APPLICATION above AGL FRAMEWORK
     Date:    09 juin 2016
     Author:  JosÃ© Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 Programmation Languages for Applications
 -----------------------------------------
@@ -166,6 +166,8 @@ Checking on closed session for uuid should be refused:
 
 #### Using afb-client-demo
 
+> The program is packaged within AGL in the rpm **libafbwsc-dev**
+
 Here is an example of exchange using **afb-client-demo**:
 
     $ afb-client-demo ws://localhost:1234/api?token=123456
@@ -202,6 +204,24 @@ Replies use javascript object returned as serialized JSON.
 This object contains at least 2 mandatory fields of name **jtype** and **request**
 and one optional field of name **response**.
 
+### Template
+
+This is a template of replies:
+
+```json
+{
+   "jtype": "afb-reply",
+   "request": {
+      "status": "success",
+      "info": "informationnal text",
+      "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+      "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+      "reqid": "application-generated-id-23456"
+   },
+   "response": ....any response object....
+}
+```
+
 ### Field jtype
 
 The field **jtype** must have a value of type string equal to **"afb-reply"**.
@@ -240,19 +260,39 @@ Value returns in the reply has the exact same value as the one received in the r
 
 This field response optionally contains an object returned when request succeeded.
 
+Format of events
+----------------
+
+Events are javascript object serialized as JSON.
+
+This object contains at least 2 mandatory fields of name **jtype** and **event**
+and one optional field of name **data**.
+
 ### Template
 
-This is a template of replies:
+Here is a template of event:
 
-    {
-      "jtype": "afb-reply",
-      "request": {
-           "status": "success",
-           "info": "informationnal text",
-           "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
-           "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
-           "reqid": "application-generated-id-23456"
-         },
-      "response": ....any response object....
-    }
+```json
+{
+   "jtype": "afb-event",
+   "event": "sample_api_name/sample_event_name",
+   "data": ...any event data...
+}
+```
+
+### Field jtype
+
+The field **jtype** must have a value of type string equal to **"afb-event"**.
+
+### Field event
+
+The field **event** carries the event's name.
+
+The name of the event is made of two parts separated by a slash:
+the name of the name of the API that generated the event
+and the name of event within the API.
+
+### Field data
+
+This field data if present holds the data carried by the event.
 
diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md
index 8427b736..83472d51 100644
--- a/doc/afb-daemon-vocabulary.md
+++ b/doc/afb-daemon-vocabulary.md
@@ -4,7 +4,7 @@ Vocabulary for AFB-DAEMON
     Date:    27 mai 2016
     Author:  JosÃ© Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 ## Event
 
diff --git a/doc/afb-overview.md b/doc/afb-overview.md
index 2ae8e066..1bd83240 100644
--- a/doc/afb-overview.md
+++ b/doc/afb-overview.md
@@ -4,7 +4,7 @@ Overview of AFB-DAEMON
     Date:    30 mai 2016
     Author:  JosÃ© Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 Roles of afb-daemon
 -------------------
diff --git a/doc/afb-plugin-writing.html b/doc/afb-plugin-writing.html
index eaa7a370..6c866fb6 100644
--- a/doc/afb-plugin-writing.html
+++ b/doc/afb-plugin-writing.html
@@ -5,6 +5,7 @@
   
   
   
+  
   HOWTO WRITE a PLUGIN for AFB-DAEMON