How to plan your first project with microservices and Spring Boot

This blog post is about a possible way of how to prepare and plan your first microservices project. It describes the basic steps which are usually need to be done before you actually can start coding.

To proceed with the blog post, you need to be familiar with:

• REST API
• Spring Boot framework and know how to create a simple project.
• microservices architecture

WHY PLANNING?

When I was a freelance developer, I did not care about too much planning of an application if I had an idea. I would just do a minimal to-do list so that I could just keep track of my activity during the day, and go straight to coding. For me that was enough, since I was the one doing all the work.

When you work in the company, that is totally another story. Depending on the company of course, but in most cases you are not the one who is doing all the job anymore. Usually you are added to a team of developers who are going to cooperate on a project together.

And here planning is crucial for the following reasons:

1. Everyone sees the project differently
2. Everyone is going to work and contribute to the same project
3. Everyone uses different tools for implementation

If planning is done properly and in a right way, everyone can be on the same page, understand every project detail in a same way and use the same tools for development.

STEP 1 - Define Microservices

As you already know, microservices is an architectural style that structures an application as a collection of services.

With simple words, its many small applications which are part of a large application. They are small, independent, easy to maintain and test, and they can be developed separately by a small team.

It is a good practice to define a microservice according to single responsibility principle. It means that one microservice should be responsible just for one task.

Sometimes its difficult to define those logical or business tasks, in some cases they're obvious (for example, with online web shops there definitely would be a microservice for the user or product). Anyway, the important step 1 is to try to define them all at the beginning.

Each microservice should be a separate SpringBoot project, its a good practice to do so if we want to use different technologies for each of them.
For example, one of them could be written in Java and use PostgreSQL database, another one could be written in Kotlin and use MongoDB.

STEP 2 - Define Endpoints

After we have decided, what microservices will be in our application, we can start defining endpoints for API for each microservice.

API Endpoint in simple words is an URL of a service. It is like a location, from which APIs can get the resources they need.

One API can provide multiple endpoints. Every endpoint operates through request and response - Client sends the request and Endpoint sends back the response.

Usually the SpringBoot application runs on localhost:8080, so if our application is for example a clothes shop, one of API Endpoints could be like this:

http://localhost:8080/clothes

When such URL will be obtained by the browser, the browser will make GET request and receive the list of clothes in return.

So, in this second step we make sure we define all the endpoints for our application (for example for the most important HTTP requests like GET, POST, PUT or DELETE etc).

STEP 3 - Define classes

No, we still cannot write any code importunately :) I know how eager you are to start coding at this stage, but be patient, we are almost done with the preparations.

Here at this point we define all the classes we would use in the application. We are pretty much now have the full overview and clear understanding of what exactly would be as building blocks of the app.

We can also write down what attributes and methods each class will have and what type each attribute will be.

STEP 4 - Write Userstories

User story is a part of Agile project management. It is an informal description of a software feature from the perspective of the end user.

A good and simple user story should be a sentence, written according to this template:
“As a [persona], I [want to], [so that].”

For example: "As a customer, I want to be able to update my info, so that I can change first name"

When we break our tasks into concrete user stories and add proper description to them, it means that any developer who will implement the feature, will know exactly what to do.

To learn more about user stories, here is a good article - User Stories with Examples and Template

STEP 5 - Prepare wireframes

After we are done with all the above preparations for the app logic, we can think about its visual look. This step is important, since it let us visualize how exactly our application will look like on the page.

There are hundreds of tools and websites available for doing sketching/ wireframing online or locally (for example such as Sketch or Figma). There is also a good tool which allows to collaborate with other developers live and draw the sketch together - https://excalidraw.com

Wireframing helps to understand and clarify:

• how many pages will you application have
• what would be the general layout as well as layouts for desktop and mobile view
• how header and footer will look like and on which pages they will repeat
• how the pop-up windows will look like

After the wireframing of each page is done, we should have solid understanding and view about the application we are going to build. Now we can start actual coding! :)