api v3 guidelines

API v3.x Guidelines

Since version 3.0 the Javascript API supports also V8 engine. This requires redesign of the API itself in an incompatible way, because the Java objects from the JVM are not directly accessible and manageable from the Javascript engine as it is the case for the Rhino and Nashorn engines.

API developers have to follow the rules below when introducing new APIs, which require communication with the JVM underneath:

1. From the Java side a "facade" has to be implemented with public static methods, which are supposed to be called by the Javascript engine.
2. The facade's methods must have input and output parameters only as primitives.
3. In case of complex parameters needed, a serialization and deserialization to/from JSON have to be considered.
4. The Java facade and Javascript API module should relate to each other 1:1
5. The Javascript modules must be placed in repositories in the GitHub's DirigibleLabs organization following the naming convention "api-v3-XXX" where the XXX is the particular name of the API group of modules e.g. core, http, utils, etc.
6. The repository should have a root folder named in the same way as the API group part of the repository following the subfolder "v3". All the modules in this group should be placed under "v3" subfolder and below.
7. A separate module in the main Eclipse Dirigible repository have to be created under the "content" subfolder containing all the "webjars" modules.
8. The necessary test cases have to be introduced in the "dirigible-api-tests" module, to guarantee the compatibility between the Javascript engines.