. . .

Development Cycle

Starting with ApiOmat 20.03, you can develop your own microservices in ApiOmat. These services are generated by the Brewer service .
The development cycle of an ApiOmat microservice is described on this page. It consists of the following steps:

  1. Model your service via the ApiOmat Dashboard.

  2. Download your service and retrieve project assets.

  3. Develop your service and deploy the source code to a repository.

  4. Start your service.

  5. Retrieve existing logic & code-first approach.

Model your service

The first step of your journey to a complete ApiOmat service is to model your classes via the Dashboard.
 To create a new service and its classes, login to the Dashboard with your customer account and:

  1. Go to the Market page (1) and choose Services in the upper left select box (2), then click on "New Service" in the top sub-menu (3):

    images/download/attachments/95832389/Screen-Shot-2020-02-21-at-09.06.37.png

  2. Enter your information in the form and click on "CREATE":

    images/download/attachments/95832389/Bildschirmfoto-2020-01-31-um-13.52.27.png

  3. Go to the Class Editor and create/edit your classes for your newly created service (like you may already know from module development )

When all of your models are ready to go, you can download the service assets and start including your logic.

Download your service and retrieve project assets

Services can be downloaded via the Dashboard:

  1. Go to the main page of your service by clicking on Use in the service version dropdown menu:

    images/download/attachments/95832389/Unbenannt2.png



  2. Click on the 'Download' button to get a ZIP containing your service's assets.

    images/download/attachments/95832389/Screen-Shot-2020-02-27-at-13.57.08.png

When you download a service, the Brewer service will be requested and will retrieve the current state of your service models from YAMBAS.

At this point we are only taking services freshly modeled in the Dashboard, for which no specific logic has been written yet, into consideration. As you may wonder how specific logic will be handled when the service is downloaded again, please keep this in mind as we will look into these points later.

After unzipping the service archive, you can import the project assets into your favorite IDE and start development.

Develop your service and deploy it

If you are not yet familiar with service development and the service assets, please refer to our Service Development Basics guide .

When you are finished with development, the next step is deploying your service archive to a repository. In the ApiOmat cloud, the default repository is Innkeeper , a service we provide for archive hosting. The default distribution manager, configured in your service's pom.xml file, refers to the Innkeeper repositories (for both released and snapshot archives).

You can deploy a service with this Maven deploy goal:

Deploy the service
mvn clean deploy -DcustomerName=<CUSTOMER_NAME> -DcustomerPassword=<CUSTOMER_PASSWORD>

The additional customerName and customerPassword parameters are part of a Maven plugin we provide for service development, the brewer-maven-plugin . As part of the Maven deploy workflow, we integrated a pre-deploy goal to ensure that the service exists in your ApiOmat environment before deploying it. Refer to the plugin documentation for more information about the pre-deploy parameters and specific behavior.

Internally, YAMBAS will be notified when a new artifact is deployed to Innkeeper. YAMBAS will then retrieve the artifact asynchronously and process it. During this process, the classes and their attributes will get updated to the same state as those in the artifact. Once this processing is done, you will be able to start your service.

Start your service

A concrete example of how to start a service is described in the Start your Service tutorial step. In this section, we will discuss the process behind it.

When you start your service from the Dashboard, the following steps will occur:

  1. The Dashboard will send a notification to the Executor service with deployment information to start the service, this information includes:

    1. A deployment ID to identify the service version job.

    2. The location of the service artifact, so the configured engine in Executor can retrieve it.

    3. Some internal parameters such as maximum memory usage.

  2. In the first version of ApiOmat services, the default engine supported by Executor is Nomad . Executor will use the Nomad API to start a job with the deployment information provided by Dashboard.

  3. Executor starts your service:

    1. Nomad retrieves the service artifact from Innkeeper and stores it.

    2. The service is started with the parameters provided by Dashboard.

    3. Once started, the service will register itself to Consul.

    The Dashboard will query Consul to check the service's healthiness and display it as described in the Service health checks documentation.


images/download/attachments/95832389/startService.png


Retrieve existing logic & code-first approach

After a service has been deployed or processed by YAMBAS, or after further changes to the classes via the Dashboard, you can download the current state from Brewer by using the download goal of the brewer-maven-plugin within your project:

Download updated artifact
mvn brewer:download -DcustomerName=<CUSTOMER_NAME> -DcustomerPassword=<CUSTOMER_PASSWORD>

It is still possible for you to download the service from the Dashboard, of course. The default behavior will be to merge the existing sources from Innkeeper with the newly generated models. This behavior gives you the possibility to share your service's sources between developers and update your service's models and API automatically when a model is changed via the Dashboard.

With the code-first approach, you can also add attributes to your data models (make sure to follow the ApiOmat type conversion as described in the Accessing Data Services documentation ): Once your service artifact has been deployed to Innkeeper, YAMBAS will be notified of the modification and your service's metadata will get updated. You can see the change in the Dashboard's data editor after the artifact has been correctly processed by YAMBAS.

Be aware that the models will be generated again every time you download the service - so when using the code-first approach, don't add any specific logic to the model classes, as everything except their attributes will be overwritten!

Additional notes on downloading and uploading

In this section, we will list common problems and misleading behavior that may occur when downloading service artifacts or deploying them to Innkeeper, and how to avoid them.


Case 1: Alice makes changes to a service and deploys it to Innkeeper. Then, Bob deploys his own changes to the same service without downloading Alice's updates first.

Problem: Bob's changes will be kept in Innkeeper, and all changes made by Alice will be lost.

Recommended behavior: Before deploying a service to Innkeeper, make sure to download it first.


Case 2: Alice modifies the generated API controller implementation (<Class>ApiImpl.java) of her service, deploys the change to Innkeeper and then downloads her service again.

Problem: The changes made to the API controller are lost after downloading the service.

Recommended behavior: During the generation/download process, all the generated classes from your service's main java package will be overwritten except for the specific data model service implementations. If you want to provide your own API controller implementation, you should create your own controller with a different name than the generated ones.


Case 3: Alice and Bob both work on the same classes within the same service version. Bob deploys his local changes to Innkeeper and Alice downloads them.

Problem: The changes made by Bob are lost on Alice's local workspace, but Alice's own changes remain. The download feature doesn't handle content merging within files.

Recommended behavior: Communication is key - use version control, e.g. Git, if you plan on working on the same sources in parallel.

Next steps

  • Have a look at the tutorial which provides a complete example of the service development cycle.