---
title: "REST API development with Spring Boot and Platform Tools"
canonical: "https://onesaitplatform.refined.site/space/DOCT/2221616312/REST%20API%20development%20with%20Spring%20Boot%20and%20Platform%20Tools"
format: markdown
---
> Macro (toc)
### Introduction
This article will show the development lifecycle using Spring Boot as the base technology for building the API. This API will be connected against a MongoDB instance and deployed as a Docker container on the CaaS platform included in Onesait Platofmr.
Platform services, such as Identity Manager, API Manager, and microservices deployment support, will be used to speed this up.
> ℹ️ INFO
> ℹ️
> ℹ️ The code for this example is available in this Github repository: [https://github.com/onesaitplatform/onesaitplatform-spring-boot-example](https://github.com/onesaitplatform/onesaitplatform-spring-boot-example) .
### Preparing the Development Environment
The API we are going to develop is based on these technologies:
- Java 8 (or higher) as the base technology for development.
- Spring Boot 2 as the development framework.
- MongoDB as the NoSQL database to store the data.
- Eclipse as the IDE.
- Maven as the project construction tool.
- JUnit as the test technology.
> ℹ️ Onesait Platform offers an SDK for Windows that integrates all these pieces, so that a developer doesn't have to install them on their own.
> ℹ️
> ℹ️ You can see how to install it in this post: [How to run the platform in my Windows PC with OP-SDK?](https://onesaitplatform.atlassian.net/wiki/spaces/OP/pages/7897242)
## API development with Spring Boot
### Creating your application's skeleton
The easiest way to start a Spring Boot application is to access the Spring Initializr website ([https://start.spring.io](https://start.spring.io)) and configure the settings of your Spring Boot application:
You will use MongoDB as a NoSQL database for data storage and Spring Data to work on top of Mongo, and Spring Web to create the REST API.
To work with Mongo, you will need a Mongo instance to work on, either containerised or installed in your local environment.
Once you have it launched, configure it in the application.yml of your Spring Boot application.
### Creating the Message entity
For starters, create the **Message **entity as the class that represents the document in MongoDB. To do this, use the @Document annotation and mark the idMessage field as @Id.
Para empezar crearemos la entidad **Message **como clase que representa el documento en MongoDB, para ello haremos uso de la anotación @Document , y marcaremos el campo idMessage como @Id
### Creating the repositories
Spring Data MongoDB comes with a set of methods for queries that it implements underneath, but for more complex queries, such as grouping by state, you will need to implement the method.
**MessageRepository**
In this class, you will extend both MongoRepository and your custom repository, where the custom operations to implement will go:
**MessageRepositoryCustom**
As we said, here are the definitions of the custom operations:
As you can see, two new classes appear as the return methods: TypeAggregationResults and StatusAggregationResults. These are DTOs to map the result of the queries, because obviously no Message structure is returned for grouping queries.
The DTO also has the percentage field to be able to return the result with %.
**MessageRepositoryImpl**
Here you will implement the methods defined in the interface. Bear in mind that the class must be called as the MessageRepository interface (which extends MongoRepository) + "Impl", so that the Spring Data MongoDB autoconfiguration works correctly.
As you can see, in the grouping operations by state and type, you have to use MongoDB's Aggregations, and also use projections.
### Service layer
A service layer will be needed to orchestrate the calls to the repository.
**MessageService**
**MessageServiceImpl**
Here you will implement the methods (see code).
### Controller and documentation with Swagger
Finally, to finish the API, you will need to define the controller layer and document it with Swagger:
In the implementation of this controller, you will make use of the service described before, MessageService (see code).
### Enable Swagger interface
You will need to add the Swagger dependencies to your project to be able to use these features.
To be able to access the Swagger interface of the application, you will have to enable Swagger 2, and configure your API.
**SwaggerConfig**
With this, you will be able to access your API when you launch the Spring Boot App:
### API functionality: sending mails
To use the Spring mail service, you have to include the **spring-boot-starter-mail **dependency in the project, and configure the properties in the application.yml:
Then you will create a service for sending mails.
**MailServiceImpl**
Now, modify the method for creating new Messages, in the MessageServiceImpl, so that when a new message is created, and it is of type Mail, it will send a mail. If everything goes well, its status will be updated to SENT; otherwise, the status is left as wrong.
### Integrating security to your API: authentication
To control who invokes your API, integrate it with the Platform Identity Manager, so that no additional parts are needed. The platform offers a library to simplify its use; make use of it: [https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/180682753](https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/180682753)
As you won't use Realms in this example, you can leave the configuration as is:
Create another REST service to log in the users of your application:
In this endpoint, users will be able to get their Oauth2 token in order to use it for Message API calls.
You will have to add another Docket to the Swagger configuration to document this authentication API:
And for the Message API, you will have to mandatorily add the Authentication header to all operations:
Lastly, you will have to configure the security, so that all the /api/message** paths are secured by the library:
Now you have your Message API secured.
And you can see how the status is updated once the email has been sent:
```
{
"idMessage": "90-90lkn-78-fhde",
"txtMessage": "NEW MESSAGE TEST",
"typeMessage": "MAIL",
"fromMessage": null,
"toMessage": "fjgcornejo@minsait.com",
"statusMessage": "SENT",
"sentDate": "2020-05-13T14:54:47.389+0000",
"errorOnSending": null
}
```
### Completing the API functionality
Now you will configure the SMS sending service. You are going to use [Twilio](https://www.twilio.com/) as a messaging service, as it offers $16 free to use its services. So, sign up, and set up a number for the trial period.
Put the Twilio SDK dependency in your project:
```
com.twilio.sdk
twilio
7.42.0
```
In the configuration properties, you will need:
Create the service with a simple method that sends messages.
Finally, modify the MessageServiceImpl service so that when it is an SMS message, it uses the service you just created:
Now you will test the service from Swagger:
And you can see how it sends the SMS and correctly updates the status of the Message:
```
{
"idMessage": "789-978hjn",
"txtMessage": "Hola esto es una prueba SMS. Irá bien",
"typeMessage": "SMS",
"toMessage": "+34616986373",
"statusMessage": "SENT",
"sentDate": "2020-05-14T09:29:26.047+0000"
}
```
You can also force an error, so that it updates the status of the message to ERROR, for example, by setting an invalid number (+1234):
```
{
"idMessage": "789-978hjn",
"txtMessage": "Hola esto es una prueba SMS. Irá mal",
"typeMessage": "SMS",
"toMessage": "+1234",
"statusMessage": "ERROR",
"sentDate": "2020-05-14T09:38:31.630+0000",
"errorOnSent": "Could not send SMS: The 'To' number +1234 is not a valid phone number."
}
```
### Deploying your API
In the case of Spring Boot development, you have to deploy the pieces that make up your local development to an environment. In this example, you will need to have a MongoDB available for storage and then deploy your API developed with Spring Boot.
There are different ways to do this depending on the environment you are working in. For the deployment of Spring Boot applications, nowadays it is standardised to deploy applications with Docker. For MongoDB there, are several ways: containerised deployment, use as a service.
The platform helps you to automate this part as the platform integrates a MongoDB among its components and allows you to deploy Spring Boot applications in a simple way on the integrated CaaS platform.
To deploy your API (Spring Boot application), you will have to dockerise it first. To do so, you will have to create a structure like the following:
- sources/
- docker/
- Dockerfile
- src/main/resources
- application-docker.yml
Then deploy the microservice on the Platform: [https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/183599130](https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/183599130)
In the **application-docker.yml **, overwrite the properties that will change on each deployment:
```
server: ## Config Web Server
port: ${PORT}
servlet.contextPath: ${CONTEXT_PATH}
spring:
data:
mongodb:
uri: mongodb://${MONGO_SERVER}:27017/${MONGO_DB}
openplatform.api:
baseurl: https://${ONESAIT_SERVERNAME}
## LOGGING CONF
logging:
path: /var/log
file: ${spring.application.name}
level:
com.minsait: DEBUG
org.springframework.security: INFO
```
The Dockerfile will look like this:
```
FROM openjdk:8-jdk-alpine
# Metadata
LABEL module.name="spring-boot-demo"
COPY *.jar app.jar
# logs folder
RUN mkdir -p /var/log && \
mkdir ./target
# create user
RUN addgroup -S user -g 433 && adduser -u 431 -S -g user -h /usr/local -s /sbin/nologin user
RUN chown -R user:user /var/log && \
chmod -R 777 /var/log && \
chown user:user app.jar && \
chown -R user:user ./target && \
chmod -R 777 ./target
VOLUME ["/var/log"]
USER user
EXPOSE 8080
ENV JAVA_OPTS="$JAVA_OPTS -Xms1G -Xmx3G" \
ONESAIT_SERVERNAME=development.onesaitplatform.com \
PORT=8080 \
CONTEXT_PATH=/spring-boot-demo \
MONGO_SERVER=mongodb-demo \
MONGO_DB=spring_boot_demo
ENTRYPOINT java $JAVA_OPTS -Djava.security.egd=file:/dev/./urandom -Dspring.profiles.active=docker -jar /app.jar
```
Once you have these files in the repository, you can proceed to create the microservice on the platform.
About the Gitlab, Jenkins and Rancher configurations, if they have not been configured by the platform environment administrator, you will have to configure them ourselves, with the requested credentials.
Once created, you can generate the image that you will deploy.
When the generation is finished, you can proceed to deploy the microservice, but first, you must deploy a Mongo so that your application can use it.
For this, generate a stack in the CaaS Platform, and put a service with the mongo:4.0 image.
Once ready, you can deploy your microservice, in the stack you just created:
Now you have the service deployed in your stack:
And you can invoke it from the URL:
### Managing the API lifecycle from the Portal API
Although you can make use of the API from the URL indicated above, you can publish the API as an external API in the API Manager to be able to make use of the lifecycle management that the onesait Platform does, explained here: [https://onesaitplatform.atlassian.net/wiki/spaces/OP/pages/327878/Lifecycle+of+REST+APIS+in+Platform](https://onesaitplatform.atlassian.net/wiki/spaces/OP/pages/327878/Lifecycle+of+REST+APIS+in+Platform)
Go to APIs and create an external REST API, indicating the URL of the swagger.json of our service. This URL can be found here:
Now your Spring Boot API will be managed by the API Manager, so you will be able to invoke it through it:
> ℹ️ This way the API security could be handled by the API Manager, and you could skip the security configuration with the library described in the previous section: Integrating security to your API: authentication