Microservice Best Practices: Getting Started
Tags: microservices, iot, bestpractices, gettingstarted
Published: 2024-06-18 12:20:35

---
title: Microservice Best Practices: Getting Started
published: true
date: 2024-05-21 06:58:11 UTC
tags: Microservice, iot, BestPractices, GettingStarted
canonical_url: https://tech.forums.softwareag.com/t/microservice-best-practices-getting-started/295033/1
---

 

## Overview

This article is part of the [Article series on Microservices Best Practices for Cumulocity IoT](https://tech.forums.softwareag.com/t/microservices-best-practices-article-series-for-cumulocity-iot/294836). The goal of this Tech Community article series is to address the need for Best Practices for Microservices Development.

The article serves as a starting point and provides an introduction to the concept of microservices in Cumulocity IoT as well as pointers to the most important libraries and tools that help you when developing a microservice. To wrap things up, we will develop our first microservice together and run it both locally and deploy it to Cumulocity IoT.

The article focuses on developing microservices using Java and the official Microservice SDK for Java. It is possible to develop microservices in other languages but these approaches will only be mentioned in passing here and will be covered in detail by separate articles in this series.

## Microservices in Cumulocity IoT

[Microservices](https://cumulocity.com/docs/microservice-sdk/microservice-sdk-introduction/) are server-side applications that run within Cumulocity IoT that are used to extend the platform with customer-specific functionality. Typically, they are the first choice when integrating Cumulocity IoT with other systems (a detailed discussion of the options for system integration can be found here [Exploring System Integration options for Cumulocity IoT](https://tech.forums.softwareag.com/t/exploring-system-integration-options-for-cumulocity-iot/288341)).

Besides system integration, microservices are also used in a variety of other use cases:

- Server-side device agents for devices that cannot run thin-edge or a custom Cumulocity IoT agent

- Mapping functionality for [Device Protocols](https://cumulocity.com/docs/protocol-integration/device-protocols/)

- Backend functionality for custom Cumulocity IoT solutions

A microservice running in Cumulocity IoT is a Docker container that is running on a Kubernetes infrastructure. Like other Docker containers, it should not use the local file system for long-term persistence as its contents will not be available across service restarts. Cumulocity IoT microservices do not support persistent volumes to be mounted, so they are not a good choice to run e.g. databases or messaging systems.

A microservice can interact with the Cumulocity IoT tenant on which it is subscribed through credentials that are injected into the container at run-time. It can provide a REST API that is accessible as a service under the domain of the Cumulocity IoT tenant thus making it accessible by Cumulocity IoT Web applications without running into cross-site restrictions. Microservices can interact with external systems as long as they are accessible from the Cumulocity IoT instance, which typically means accessible from the internet. As microservices are constantly running, they are perfect candidates for running scheduled functionality.

To run for a Cumulocity IoT tenant, the microservice needs to be packaged as a Docker container image. That image needs to be bundled into a zip file together with the microservice manifest. The [microservice manifest](https://cumulocity.com/docs/microservice-sdk/general-aspects/#microservice-manifest) is a JSON file that describes how the microservice should be run. It includes the required resources, information about scaling the microservice to additional instances, and required permissions for the Cumulocity IoT API as well as settings for monitoring the microservice.

[![image](https://global.discourse-cdn.com/techcommunity/optimized/3X/c/0/c08ef57369bfdd74bfb158c1c42c7b0264bac317_2_690x259.png)](https://global.discourse-cdn.com/techcommunity/original/3X/c/0/c08ef57369bfdd74bfb158c1c42c7b0264bac317.png "image")

All traffic to the microservices on Cumulocity IoT goes through the Core Node, enforcing the security already in place. There is no direct access to the microservice.

Microservice can run in two isolation modes: per-tenant and multi-tenant. In per-tenant isolation mode each tenant that is subscribed to a microservice will get its own instance. In multi-tenant isolation mode a single instance is shared between multiple tenants. Multi-tenant microservice can make better use of resources as it is likely that activity peaks are distributed more evenly across multiple tenants. The microservice receives credentials for each tenant on which it is subscribed and must take care to perform activities on the right tenant. In general, it is recommended to implement microservices as if they run in multi-tenant isolation mode even if you do not plan to take advantage of this at the moment as it can be difficult to make all the necessary adjustments later on. The details of developing a multi-tenant microservice will be covered in a separate article.

The ability to deploy microservices is available both on Cumulocity IoT Cloud and Cumulocity IoT Edge. On a cloud, it is an optional feature that needs to be enabled and incurs additional costs per assigned resource. On Cumulocity IoT Edge, the [microservice hosting feature](https://cumulocity.com/guides/edge/configuration/#configuring-microservices) needs to be enabled explicitly as it increases the minimum system requirements (even without any microservices being deployed).

## Getting Started with Development

This section introduces the most important resources that will help you on your journey to develop microservices.

### Microservice SDK and unofficial clients

Developing Cumulocity IoT microservices in Java using the official [Microservice SDK](https://cumulocity.com/docs/microservice-sdk/microservice-sdk-introduction/) is the default choice for microservice development. The Microservice SDK provides built-in support for multi-tenant microservices including the management of service user credentials and support for user and tenant scopes that make it easy to invoke the Cumulocity IoT API either on behalf of a user or on behalf of the microservice.

The Microservice SDK is built on top Spring Boot, which makes it easy use the wide range of Spring Framework libraries to implement REST service, to run scheduled functionality or to integrate with 3rd party systems. The example in the next section will use the Microservice SDK.

Not everyone wants to develop microservices in Java, though. This can be due to existing code in another programming language or personal preferences. Also Java microservices typically result in large Docker images ([though there are ways to reduce the size](https://tech.forums.softwareag.com/t/migrate-java-microservices-from-java-8-to-java-11/242978)) and consume significant memory resources.

So if you decide against using Java and the Microservice SDK there are plenty of options:

- [Cumulocity IoT API](https://www.cumulocity.com/api/core/) - can be used directly in any programming language.
- **C#** - an unofficial SDK is available [here](https://github.com/SoftwareAG/cumulocity-sdk-dotnet) and the authors talk about it in this tech talk [IoT Tech Talk - C# Microservice Development](https://tech.forums.softwareag.com/t/iot-tech-talk-c-microservice-development/293824)
- **Python** - an unofficial Python API is available [here](https://github.com/SoftwareAG/cumulocity-python-api). The author gives an introduction to the library in this article: [Getting started with the Cumulocity Python API](https://tech.forums.softwareag.com/t/getting-started-with-the-cumulocity-python-api/264700). The samples folder contains examples of single-tenant and multi-tenant microservices built using the library.
- **Typescript** - there is no ready to use SDK but this article [How to write a "truly" multitenant microservice in typescript](https://tech.forums.softwareag.com/t/how-to-write-a-truly-multitenant-microservice-in-typescript/289943) explains how to build a Typescript microservice from scratch. It is recommended reading even if you do not want to build microservices in Typescript as it explains the concepts behind microservices and you can easily adapt this to the programming language of your choice.
- **Rust** - [This repository](https://github.com/SoftwareAG/cumulocity-rust-ms-example) contains an example of a Rust microservice, which results in a very small microservice image.

### go-c8y-cli for Microservice Development

If you do not know about [go-c8y-cli aka Cumulocity IoT CLI](https://goc8ycli.netlify.app), go check out the video and the documentation linked above. It provides an extremely user-friendly command line interface to the Cumulocity IoT that can be used in scripts to achieve anything from migrating data to simulating devices. In the TechCommunity you can find this introduction [Have you ever used go-c8y-cli?](https://tech.forums.softwareag.com/t/have-you-ever-used-go-c8y-cli/288498)

This article [Easily run your java microservice locally with go-c8y-cli](https://tech.forums.softwareag.com/t/easily-run-your-java-microservice-locally-with-go-c8y-cli/291214) explains how go-c8y-cli simplifies the process of running microservices locally during development. In our example in the next section, we will use this approach instead of the one from the official documentation as it is much simpler.

### Templates and Maven Archetype

Finally, before we are getting to develop our own microservice, two additional resources that can help you tremendously:

- [cumulocity-microservice-archetype](https://github.com/SoftwareAG/cumulocity-microservice-archetype) - a Maven archetype that creates the basic project structure of a Java microservice using the SDK for you.
- [Microservice templates](https://github.com/SoftwareAG/cumulocity-microservice-templates/tree/main) - this repository contains a number of examples that you can use as a starting point for you own development.

## Create your first Java Microservice

As a last step in this article, we will together build your first microservice together. We are going to use the Cumulocity Microservice Archetype and go-c8y-cli. So first we need to setup both.

## Prerequisites

- Follow [these instructions](https://github.com/SoftwareAG/cumulocity-microservice-archetype?tab=readme-ov-file#run) to install the Maven archetype

- Follow these instructions to [install](https://goc8ycli.netlify.app/docs/installation/shell-installation/) and to [configure](https://goc8ycli.netlify.app/docs/gettingstarted/) go-c8y-cli

### Step 1 - Create a Microservice project

Now we can create the microservice project. Make sure that go-c8y-cli is enabled to use the right tenant:

```
set-session

```

Now run Apache Maven to create the project:

```
   mvn archetype:generate -DarchetypeGroupId=cumulocity.microservice -DarchetypeArtifactId=cumulocity-microservice-archetype

```

Answer the three questions like this:

- Choose name: helloworld
- Define value for property ‘artifactId’ cumulocity-microservice-helloworld: : (keep suggestion)
- Define value for property ‘package’ cumulocity.microservice.helloworld: : com.mycompany.helloworld

### Step 2 - Create Cumulocity IoT Microservice Application for local development

After the microservice project has been created switch into its directory and create the microservice application on your Cumulocity IoT tenant:

```
c8y microservices create --file src/main/configuration/cumulocity.json --name helloworld

c8y microservices getBootstrapUser --id helloworld

```

The output of the second command will be a table like this

```
| tenant | name | password |
|----------------|----------------------------------|---------------------------------------|
| t... | servicebootstrap_helloworld | ... |

```

Open the IDE or editor of your choice and open the file _src/main/resources/application-dev.properties_. Provide values for the following properties:

- **C8Y.bootstrap.tenant** - tenant id from column 1 above
- **C8Y.baseURL** - the URL of your Cumulocity IoT tenant
- **C8y.bootstrap.user** - the user name from column 2 above
- **C8Y.bootstrap.password** - the password from column 3 above

### Step 3 - Run the microservice

You can now package and run your microservice:

```
mvn package

java -jar target/cumulocity-microservice-helloworld-1.0.0-SNAPSHOT.jar

```

You can also run or debug the **App** main class of your microservices directly if your IDE supports this.

The microservice already supports two endpoints (authentication using tenantid/user):

- [http://localhost:8080/health](http://localhost:8080/health) - a standard endpoint that provides statistics about the status and resource consumption of your microservice
- [http://localhost:8080/api/hello/devices](http://localhost:8080/api/hello/devices) - an example of a REST endpoint that lists all devices of your tenant.

The latter should be replaced by your actual microservice implementation.

### Step 4 - Project overview and customization

[Read full topic here](https://tech.forums.softwareag.com/t/microservice-best-practices-getting-started/295033/1) to learn about project overview and customization.

## Summary

This article provided an introduction into the concept of microservices in Cumulocity IoT, listed the most important resources to develop microservices using both the standard Microservice SDK for Java as well as other programming languages, and helped you to create your first microservice.

The article is part of the [Microservices Best Practices article series for Cumulocity IoT](https://tech.forums.softwareag.com/t/microservices-best-practices-article-series-for-cumulocity-iot/294836). Future articles of the series will dive deeper into the concepts introduced in this article.