Provide API documentationv1.0.01.0.0-ONAP1.0.0-Amsterdam

Create global offeredapis.rst
Create offeredapis.rst per parser
javatoscachecker API based on service/README file

Change-Id: I8739791a083c4e62112910bd21cb02cf4bf41a95
ISSUE-ID: MODELING-37
Signed-off-by: Eric Debeau <eric.debeau@orange.com>

6 files changed, 162 insertions, 93 deletions

diff --git a/docs/index.rst b/docs/index.rst
index f3b8d30..4dbd373 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,6 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-The documentation for tosca parsers
+The documentation for TOSCA parsers
 ===================================
 
 
@@ -8,4 +8,6 @@ The documentation for tosca parsers
    :maxdepth: 1
 
    javatoscachecker/index
-   nfvparser/index
\ No newline at end of file
+   nfvparser/index
+
+   offeredapis
diff --git a/docs/javatoscachecker/checker.rst b/docs/javatoscachecker/checker.rst
index 01321b0..2289a66 100644
--- a/docs/javatoscachecker/checker.rst
+++ b/docs/javatoscachecker/checker.rst
@@ -1,89 +1,110 @@
-1. History

-==========

-

- * Development started over 2 years ago as part of the Network Automation, the Intelligent Service Composition project

- * It was supporting the model driven composition of resources/services/products

-

-2. Scope

-========

-

- * Development of a tool as generic as possible

-   - not bound to a particular schema/profile

-   - no particular type of post-processing (orchestrator)

-   - limited to TOSCA yaml profile

-   - Java language

-

-3. Goals

-========

-

- * Ensure that a (set of) TOSCA template(s)is conform to a correctly defined type system

-   - avoid errors at more expensive later processing stages

-   - pre-requisite to further processing: UI rendeing, persistence

-

- * Generate an intermediate form that could facilitate further processing

- * Extensibility

-   - accommodate extensions to the standard and checks pertinent to these extensions

-

-4. The checker

-==============

-

- * Validate yaml document

-   - supports streaming documents (multiple documents within one file), yaml anchors, etc

-   - currently uses the snakeyaml library

- * Syntax check

-   - two pre-defined grammars, 1.0 and 1.1, with the possibility of handling a mix of documents version wise

-     + other versions/variants can be added 'on the fly', identified through the tosca_definitions_version entry

-   - accept the short forms

-     + declare the short forms within the grammar

-     + builds a canonical form from which the shorts forms are eliminated (so further processing steps do not need to handle them)

-   - grammar written in yaml

-     + easy to maintain/modify

-     + processed through a modified version of the kwalify library

- * Checks

-   - type hierarchy checks for all constructs

-     + valid re-definitions: from relatively simple (properties) to rather complicated (interface opearations)

-   - valid type references: all referenced types are pre-declared (as super-types, as valid source types, etc)

-   - templates respect their respective type definition

-     + example: check type of interface operation inputs

-     + other references: capabilities and requirements in substitution mappings

-   - data checks: assignments match the type specification, function argument compatibility (for built-in functions), constraints matching

- * Process the entire document tree specified through import statements

- * Extensibility

-   - pluggable document locator/loader

-   - pluggable handlers at syntax check (pre/post validation)

-   - pluggable checks based on document location

-     + a new construct (new grammar) can be subject to new semantic checks plugged without checker code being re-built.

-

-5. Output

-=========

-

- * Error reporting

-   - Differs depending on the stages

-     + Document position indication during parsing

-     + Document path and rule during syntax check

-     + Document path during checking

- * Catalog

-   - No explicit representation of TOSCA constructs, offers a query interface with results being exposed as common Java types: maps, lists, ..

-   - domain specific (TOSCA constructs) navigation built through a proxy based approach on top of above representation 

-

-6. Usage

-========

-

- * API

-   - simple API that allows access to any stage of the checker

-     + One can build an in-memory representation of a TOSCA document and skip the yaml parsing.

-     + Re-usable Catalog (hierarchical Catalogs)

-     + One or more documents can be processed and the resulting Catalog be preserved and used for later processing of other documents using the previous catalog as base catalog

- * CLI

-   - basic command line interface

- * Service

-   - stateful REST service layer on top of checker API

-     + a schema (document with type specifications) can be submitted and be referenced (imports) from subsequently submitted templates

-

-

-7. Post-processing

-==================

-

- * A tiny framework for additional processing

-   - one basic implementation of a JavaScript post-processor where the Catalog and topology graph are exposed to javascript scripts implementing business validation rules 

-

+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+History
+=======
+
+The development started over 2 years ago as part of the Network Automation, the Intelligent Service Composition project.
+It was supporting the model driven composition of resources/services/products.
+
+Scope
+=====
+
+**Development of a tool as generic as possible**
+ - not bound to a particular schema/profile
+ - no particular type of post-processing (orchestrator)
+ - limited to TOSCA YAML profile
+ - Java language
+
+Goals
+=====
+
+**Ensure that a (set of) TOSCA template(s)is conform to a correctly defined type system**
+ - avoid errors at more expensive later processing stages
+ - pre-requisite to further processing: UI rendeing, persistence
+
+**Generate an intermediate form that could facilitate further processing**
+
+**Extensibility**
+ - accommodate extensions to the standard and checks pertinent to these extensions
+
+The checker
+===========
+
+**Validate YAML document**
+ - supports streaming documents (multiple documents within one file), YAML anchors, etc
+ - currently uses the snakeyaml library
+
+**Syntax check**
+ - two pre-defined grammars, 1.0 and 1.1, with the possibility of handling a mix of documents version wise
+
+  - other versions/variants can be added 'on the fly', identified through the tosca_definitions_version entry
+
+ - accept the short forms
+
+  - declare the short forms within the grammar
+  - builds a canonical form from which the shorts forms are eliminated (so further processing steps do not need to handle them)
+
+ - grammar written in yaml
+
+  - easy to maintain/modify
+  - processed through a modified version of the kwalify library
+
+**Checks**
+ - type hierarchy checks for all constructs
+
+  - valid re-definitions: from relatively simple (properties) to rather complicated (interface opearations)
+
+ - valid type references: all referenced types are pre-declared (as super-types, as valid source types, etc)
+ - templates respect their respective type definition
+
+  - example: check type of interface operation inputs
+  - other references: capabilities and requirements in substitution mappings
+
+ - data checks: assignments match the type specification, function argument compatibility (for built-in functions), constraints matching
+
+**Process the entire document tree specified through import statements**
+
+**Extensibility**
+ - pluggable document locator/loader
+ - pluggable handlers at syntax check (pre/post validation)
+ - pluggable checks based on document location
+
+  - a new construct (new grammar) can be subject to new semantic checks plugged without checker code being re-built.
+
+Output
+======
+
+**Error reporting**
+ - Differs depending on the stages
+
+  - Document position indication during parsing
+  - Document path and rule during syntax check
+  - Document path during checking
+
+**Catalog**
+ - No explicit representation of TOSCA constructs, offers a query interface with results being exposed as common Java types: maps, lists, ..
+ - domain specific (TOSCA constructs) navigation built through a proxy based approach on top of above representation
+
+Usage
+=====
+
+**API**
+ - simple API that allows access to any stage of the checker
+
+  - One can build an in-memory representation of a TOSCA document and skip the yaml parsing.
+  - Re-usable Catalog (hierarchical Catalogs)
+  - One or more documents can be processed and the resulting Catalog be preserved and used for later processing of other documents using the previous catalog as base catalog
+
+**CLI**
+ - basic command line interface
+
+**Service**
+ - stateful REST service layer on top of checker API
+  
+  - a schema (document with type specifications) can be submitted and be referenced (imports) from subsequently submitted templates
+
+Post-processing
+===============
+
+**A tiny framework for additional processing**
+ - one basic implementation of a JavaScript post-processor where the Catalog and topology graph are exposed to javascript scripts implementing business validation rules
diff --git a/docs/javatoscachecker/index.rst b/docs/javatoscachecker/index.rst
index 288ac89..6875ff7 100644
--- a/docs/javatoscachecker/index.rst
+++ b/docs/javatoscachecker/index.rst
@@ -7,5 +7,5 @@ The documentation for javatoscachecker
 .. toctree::
    :maxdepth: 1
 
-   
-   checker
\ No newline at end of file
+   checker
+
diff --git a/docs/javatoscachecker/offeredapis.rst b/docs/javatoscachecker/offeredapis.rst
new file mode 100644
index 0000000..ca814eb
--- /dev/null
+++ b/docs/javatoscachecker/offeredapis.rst
@@ -0,0 +1,31 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Checker API
+===========
+
+**POST /check_template/**
+ - unnamed (isolated/one time) service template checking
+ - return: a json representation of the report produced by the checker (an array with json objects as elements, one per error encoutered)
+
+**POST /check_template/{catalog}/{name}**
+ - named template submitted as part of the given catalog. A catalog allows a client application to isolate a particular TOSCA schema (type system) against which other templates will be checked. The catalog names are arbitrary (see catalog GET below as a way of checking if a catalog name is in use).
+ - return: a json representation of the report produced by the checker (an array with json objects as elements, one per error encoutered). When using the catalog based api one can use import statements within the templates but .. all import references are towards templates submitted prior hence all the errors in the report are for the submitted template).
+
+.. note::
+   currently there is no explicit catalog creation API. A new catalog with the given name will be created if not already existing.
+
+**GET /check_template/{catalog}/{name}**
+ - checks if a template with the given name was submitted/checked as part of the given catalog.
+ - returns HTTP 200 OK if a catalog with that name existed and the given name is associated with a previously submitted (named) template, 404 otherwise. No other catalog or template information is returned.
+
+**POST /check_template/{catalog}**
+ - unnamed template submitted as part of the given catalog. The template is processed but not registered so it cannot be referenced afterwards; it can use import statements refering to named templates within this catalog.
+ - return: a json representation of the report produced by the checker (an array with json objects as elements, one per error encoutered)
+
+**GET /check_template/{catalog}**
+ - checks if a catalog with the given name exists
+ - returns HTTP 200 OK if a catalog with that name existed, 404 otherwise. No other catalog information is returned.
+
+**DELETE /check_template/{catalog}**
+ - deletes an existing catalog (and all information associated with it)
+ - returns HTTP 200 OK if a catalog with that name existed, 404 otherwise
diff --git a/docs/nfvparser/offeredapis.rst b/docs/nfvparser/offeredapis.rst
new file mode 100644
index 0000000..edb839e
--- /dev/null
+++ b/docs/nfvparser/offeredapis.rst
@@ -0,0 +1,5 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+NFV Parser API
+==============
+
diff --git a/docs/offeredapis.rst b/docs/offeredapis.rst
new file mode 100644
index 0000000..5fbdf3d
--- /dev/null
+++ b/docs/offeredapis.rst
@@ -0,0 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+TOSCA parsers APIs
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   javatoscachecker/offeredapis
+   nfvparser/offeredapis