. . .

Creating a new module

Creation

Since ApiOmat version 2.1.0 there are two ways to create a Native Module: Via Git and via Jar.

Via JAR

This method was the only available one before ApiOmat version 2.1.0. If you have existing Native Modules or if you don't have access to a Git repository, you can continue to use this method.

For details, see the sub page Creating a new module via JAR.

Native Modules via Git have some advantages, so you might consider migrating existing JAR Native Modules.

Via Git

This method is available since ApiOmat version 2.1.0 and allows you to create and maintain Native Modules in a Git repository. This way you don't have to manually download and upload your Native Module to ApiOmat via Ant Scripts. Instead, you only need to maintain a Git repository with your Native Module code (which you probably have anyway) and ApiOmat accesses that repository to pull and push changes automatically.

For details, see the sub page Creating a new module via Git.

Adding classes, releasing and deploying

After you created the (so far) empty module, you can add classes and release and deploy the module.

Adding classes

Now classes and attributes can be created in the Dashboard. This is also possible using cURL and can be looked-up at Using the REST interface.

Yet another way to create new classes and attributes is to directly amend the sourcecode while using the switch

update=true

in the sdk.properties file in order to automatically generate the new meta models and meta model attributes upon upload. A new class must be annotated with "@Model":

@Model( moduleName = "MyModule", isTransient = false, isInvisible=false)

The value of the attribute "moduleName" should equal the name of the own module while "isTransient" can be used to declare whether this class is transient or not (see next chapter). You can mark a class as invisible for the REST interface; also see next chapter for more information.

Class attributes cause the generation of corresponding meta model attributes and don't require additional annotation. It is advisable to download the module right after the upload is finished in order to fetch automatically generated code.

Transient classes

By default, all data related to a class is stored in and retrieved from ApiOmat's own MongoDB. However in several use cases, data is to be stored in and retrieved from an external data source which then makes storing data in the MongoDB unnecessary. Therefore, a class can be set to transient in the Dashboard. The according cURL command looks like (METAMODELID is the id of the class):

Linux
curl -X PUT ${URL}/yambas/rest/modules/${MODULENAME}/metamodels/${METAMODELID} -d "{ \"transient\":\"true\"}" -u $AUTH -H "Content-Type:appliation/json"
Windows
curl -X PUT %URL%/yambas/rest/modules/%MODULENAME%/metamodels/%METAMODELID% -d "{ \"transient\":\"true\"}" -u %AUTH% -H "Content-Type:appliation/json"


Furthermore, the isTransient annotation can be adjusted in the source code before uploading the SDK again to achieve the same result.

The "transient" switch makes ApiOmat refrain from storing data inside its own MongoDB whilst henceforth the attribute "foreignId" will be used instead "id" to reference data of this class since "id" is only assigned by MongoDB. This can be noticed by the fact that the foreignId will conclude the HREF attributes of this class.


Example

A data model "Car" inside the module "Garage" is stored non-transient; new objects therefore receive IDs from the database while the HREF may look like:

http://.../yambas/rest/apps/models/Garage/Car/546af63abbb8c281fcc58e20

If the model has been set to transient and is stored in an external data source which creates IDs as incremental numerical values, the HREF might look as follows:

http://.../yambas/rest/apps/models/Garage/Car/123213

Finally, different hook methods will be executed; when accessing class objects, the do...() methods are called directly instead of the before..()/after..() methods. Please consult Development Basics to learn more about hook classes and other SDK classes.

Invisible classes

In some use cases not all classes should be exposed to the REST interface (neither the classes themselves, nor the data (instances of the class)). For example, when using our SQL module which crawls databases, classes of tables get created automatically, but you may not want to expose all the DB tables to the public.

To hide a class, you can set the isInvisible annotation to true.

The result will be that:

  • when you query a module's meta models, the invisible ones will only be returned for the module owner and customers with the write role for the module

  • no instances of the class can be created, fetched, updated or deleted via the REST interface

  • BUT you can work with the class and its instances in Native Module Code

You can therefore use invisible classes inside your module for implementing your business logic or store internal data.

Inheritance

If you are inheriting from a invisible class, the subclass will also get invisible for security reasons.

Releasing

The module has to be "released" if you want one of the following things:

  • The module should be accessible to other customers via the module market

  • The module should be usable (as a library) in other modules

  • The module contains a custom REST endpoint with a Swagger annotation and you want the API documentation to appear in the Apidocs

Otherwise you don't need to release your module. You can still send CRUD requests to the regular REST resources and for example create objects of a MetaModel and fetch the objects etc.

Release system specific

As of ApiOmat version 2.5.0, modules can be released for each system separately. The field "releaseState" reflects the state for the current system (depending on the "X-apiomat-system" header in request). Additionally, there is a field "releaseStates" with the current state for each system. If you update this field, the "releaseState"-field will be ignored.


To release your module, execute the following cURL command:

Linux
curl -X PUT ${URL}/yambas/rest/modules/$MODULENAME \
-d "{\"releaseState\": \"RELEASED\"}" -u $AUTH \
-H "Content-Type:appliation/json" \
-H "X-apiomat-system:$AOMSYSTEM"
Windows
curl -X PUT %URL%/yambas/rest/modules/%MODULENAME% \
-d "{\"releaseState\": \"RELEASED\"}" -u %AUTH% \
-H "Content-Type:appliation/json" \
-H "X-apiomat-system: %AOMSYSTEM%"


The "releaseState" attribute can be set via the ApiDocs or the Dashboard, as well.

You can also update the release state for multiple systems, by using the "releaseStates" field :

Linux
curl -X PUT ${URL}/yambas/rest/modules/$MODULENAME \
-d "{\"releaseStates\": {\"LIVE\":\"RELEASED\",\"STAGING\":\"RELEASED\"}}" -u $AUTH \
-H "Content-Type:appliation/json"
Windows
curl -X PUT %URL%/yambas/rest/modules/%MODULENAME% \
-d "{\"releaseStates\": {\"LIVE\":\"RELEASED\",\"STAGING\":\"RELEASED\"}}" -u %AUTH% \
-H "Content-Type:appliation/json"

Deploying

To make requests like creating or fetching objects of classes of your module, it has to be deployed. You can do this with the following cURL command:

Linux
curl -X PUT ${URL}/yambas/rest/modules/$MODULENAME \
-d "{\"moduleStatus\":{\"LIVE\":\"DEPLOYED\"}}" \
-u $AUTH -H "Content-Type:appliation/json"
Windows
curl -X PUT %URL%/yambas/rest/modules/%MODULENAME% \
-d "{\"moduleStatus\":{\"LIVE\":\"DEPLOYED\"}}" \
-u %AUTH% -H "Content-Type:appliation/json"

Deleting classes

The way you can delete classes depends on whether you've already uploaded your module:

  • If you haven't uploaded your module yet, you can simply delete the class on the dashboard

  • Otherwise, you can either delete the class by removing it from the project folder in eclipse and upload it via ant task with the "update=overwrite" property in sdk.properties or you may delete the class from the dashboard, then delete the class from your project folder in eclipse and then down- and upload the module via and task while having the properties "update=overwrite" and "merge=false" set in your sdk.properties file.

Deleting a module

By default, when calling the delete module REST resource (DELETE request to /modules/{moduleName}), the module is not deleted completely but only for the current ApiOmat system. That is, if the module is deleted in LIVE and still used in other systems like STAGING, the content of STAGING will stay untouched. If you want to delete the whole module from the ApiOmat installation, the query parameter deleteCompletely=TRUE can be provided:

Linux
curl -X DELETE ${URL}/yambas/rest/modules/$MODULENAME?deleteCompletely=TRUE -u $AUTH

* link only available in Enterprise Documentation