This post is another follow-up in the series of articles covering the technical process of building a fully fletched Java REST API for task management:

• https://blog.teonisoftware.com/step-by-step-tutorial-for-building-a-rest-api-in-java

• https://blog.teonisoftware.com/integrating-a-java-rest-api-with-a-database

• https://blog.teonisoftware.com/adding-logging-and-metrics-to-a-java-rest-api

So far, we have built the API itself, we added a storage layer using MongoDB and in the last post, we added logging functionalities as well as metrics collected through the use of Prometheus. Now, we are going to add another crucial part for every API implementation - authentication. To achieve this we are going to use another open-source product called Kratos that will provide all the standard user management features for us - registration, login, logout, email verification, etc. The authentication for the task management API will be token-based - that is the API client will register and login with Kratos and thus will receive a session token generated by Kratos. This session token will then be passed in the HTTP Authorization header in each call to the API. The task management service will extract this token from the request and call Kratos API to convert it to the corresponding user session. The extracted user will be used when creating new tasks so that we can keep a record of who created the task itself.

Current State

In the current setup, the local deployment consists of three containers:

• one for running the task management service logic

• one for running the storage layer - a MongoDB instance that stores the list of all tasks

• one for running the metrics logic - a Prometheus instance as well as a Prometheus job that periodically pulls metrics from the task management service

Docker is used as the container runtime environment and docker-compose is used to orchestrate the multi-container local deployment.

From a business logic perspective, tasks are currently anonymized - there is no notion of a task creator.

Target State

What we want to achieve at the end of this tutorial is the diagram below. The green colour is used to indicate a new component or piece of software.

From the diagram, we can see three major changes:

• new containers for deploying Kratos

  • one for running the Kratos service itself

  • one for running an auxiliary pre-built self-service Kratos UI - we will use this for registering a new user

  • one for running a mock email server to be able to send and receive emails in a local setup without using a real email provider - we will use this for verifying the email of the registered user

• new request filter used to implement authentication by using Kratos API

• a new field in the Task entity used to store a reference to the user that created the task itself

Implementation

To get to the target state, we are going to break the implementation into small steps so that the process of adding authentication can be easily understood as you follow along this tutorial.

Adding Authentication Skeleton Logic

The first step is to add a basic authentication skeleton logic:

• extracting an authentication token from the HTTP request

• converting it to the newly introduced user entity

• using the user ID as a reference for the new createdBy field for each task

We start by adding the new createdBy reference to the Task entity class. This will represent the ID of the user who created the task.

 public class Task {

    ...

    private final String createdBy;

    ...

    public static class TaskBuilder {

        ...

        private TaskBuilder(String title, String description, String createdBy) {
            validateArgNotNullOrBlank(title, "title");
            validateArgNotNullOrBlank(description, "description");
            validateArgNotNullOrBlank(createdBy, "createdBy");

            this.title = title;
            this.description = description;
            this.createdBy = createdBy;
            this.identifier = UUID.randomUUID().toString();
            this.createdAt = Instant.now();
            this.completed = false;
        }

        ...

    }
}

Then, we introduce the new User entity class. For now, we only need to retain the user ID. We won't need any more data about the user itself.

public class User {

    private final String userID;

    public User(String userID) {
        validateArgNotNull("userID", userID);

        this.userID = userID;
    }

    ...

}

Now that we have the new entity class in place, we can change the service class logic to accept a User instance as the creator for the given task. This user instance will represent the authenticated user calling the API.

public class TaskManagementService {

    ...    

    public Task create(String title, String description, User creator) {
        validateArgNotNull(creator, "creator");

        Task task = Task.builder(title, description, creator.getUserID()).build();

        repository.save(task);

        LOGGER.info("Successfully created new task {}", task);

        return task;
    }

    ...

}

The three code blocks above pretty much summarize the changes needed to be done for the business logic layer. As for the storage layer, a few small changes are needed to ensure that the new createdBy field is stored in the database:

    public static class MongoDBTask {

        ...

        @BsonProperty("created_by")
        private String createdBy;

        ...

        public String getCreatedBy() {
            return createdBy;
        }

        public void setCreatedBy(String createdBy) {
            this.createdBy = createdBy;
        }

        ...

    }

Now, let's move to the API layer. We start by introducing a new request filter, namely the AuthenticationFilter responsible for extracting the authentication token from the HTTP Authorization Header, converting it to a user instance and propagating the logged in user through the request context as a property. Because we don't have Kratos setup yet, we are going to implement a temporary logic that uses the provided authentication token as the user ID. The rest of the logic is pretty straightforward - fetching the HTTP header, validating the header value and performing a few string manipulations to extract the token from it.

@Priority(3)
@Provider
public class AuthenticationFilter implements ContainerRequestFilter {

    @Override
    public void filter(ContainerRequestContext requestContext) {
        String authHeader = requestContext.getHeaderString("Authorization");
        if (authHeader == null) {
            return;
        }

        authHeader = authHeader.trim();
        if (!authHeader.startsWith("Bearer")) {
            throw new AuthenticationException("invalid authentication scheme - please use a Bearer token");
        }

        String authToken = authHeader.replaceFirst("Bearer", "").trim();
        User user = getUserByAuthToken(authToken);
        requestContext.setProperty("user", user);
    }

    private User getUserByAuthToken(String authToken) {
        // FIXME for now use the auth token as user ID until integration with user service API is implemented
        return new User(authToken);
    }
}

Something to notice here is that we use priority 3 which is more than what we've used in the previous tutorial for the logging and the metrics filters. This ensures that the logging and metrics request filters are still going to run first and only then the authentication request filter will be executed. This is important to properly capture the request processing start time - see this part of the previous tutorial for more details.

As with any other filters, we need to register it in the application config so that it's used at runtime:

@ApplicationPath("/api")
public class ApplicationConfig extends ResourceConfig {
    @Inject
    public ApplicationConfig(ServiceLocator serviceLocator) {
        ...
        register(LoggingFilter.class);
        register(MetricsFilter.class);
        register(AuthenticationFilter.class);

        ...
    }
}

Now that a user instance is included in the request context, we can use it in the task management resource class which implements the API endpoints:

@Path("/tasks")
public class TaskManagementResource {
    private final TaskManagementService service;

    ...

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response createTask(TaskCreateRequest taskCreateRequest, @Context ContainerRequestContext requestContext) {
        validateArgNotNull(taskCreateRequest, "task-create-request-body");

        Task task = service.create(taskCreateRequest.getTitle(), taskCreateRequest.getDescription());
        User user = (User) requestContext.getProperty("user");
        Task task = service.create(taskCreateRequest.getTitle(), taskCreateRequest.getDescription(), user);

        ...
    }

    ...

}

Two key changes here:

• we used the Context annotation to instruct Jersey to inject the ContainerRequestContext instance when invoking the endpoint logic

• we used the request context to read the user property set by the authentication filter and propagate the User instance to the business logic service class

With this last step, the authentication skeleton logic is finalized. A few things that I've skipped explaining for clarity are a couple of auxiliary changes:

• adding a new AuthenticationException to handle exceptional behaviour during authentication - e.g. using the Basic scheme in the HTTP Authorization header rather than Bearer which is the standard for token-based authentication

• adding a new exception mapper that converts uncaught authentication exceptions to responses with 401 Unauthorized status codes

The full commit for what we just covered can be found here.

Kratos Container Setup

The next step for this tutorial is to add the Kratos configuration for local deployment. I am not planning to go into details about Kratos and how it works to keep this blog post simple and focused on the purpose of building a Java REST API. However, it is worth mentioning that the setup and configuration that we are using are all based on the quickstart tutorial provided by Ory on the official Kratos documentation page - https://www.ory.sh/docs/kratos/quickstart. Feel free to explore the Kratos documentation for more details.

All we need to know for this tutorial is that Kratos requires its own configuration file for deployment as well as at least one JSON schema configuration file that defines the default user identity.

We start by defining the user schema. For now, we don't need anything else apart from an email property. If you are not familiar with the JSON schema language, please refer to the official documentation.

{
  "$id": "http://localhost/schemas/user.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "title": "Email",
          "minLength": 3,
          "ory.sh/kratos": {
            "credentials": {
              "password": {
                "identifier": true
              }
            },
            "verification": {
              "via": "email"
            },
            "recovery": {
              "via": "email"
            }
          }
        }
      },
      "required": [
        "email"
      ],
      "additionalProperties": false
    }
  }
}

Next, we add the Kratos configuration file. Again, this is very specific to Kratos itself, so please refer to the official documentation for more details. An important bit to notice though is that we use the user schema defined above as the default identity schema (check the line with default_schema_id).

version: v0.13.0

serve:
  public:
    base_url: http://127.0.0.1:4433/
    cors:
      enabled: true
  admin:
    base_url: http://kratos:4434/

selfservice:
  default_browser_return_url: http://127.0.0.1:4455/
  allowed_return_urls:
    - http://127.0.0.1:4455

  methods:
    password:
      enabled: true
    code:
      enabled: true

  flows:
    error:
      ui_url: http://127.0.0.1:4455/error

    settings:
      ui_url: http://127.0.0.1:4455/settings
      privileged_session_max_age: 15m
      required_aal: highest_available

    recovery:
      enabled: true
      ui_url: http://127.0.0.1:4455/recovery
      use: code

    verification:
      enabled: true
      ui_url: http://127.0.0.1:4455/verification
      use: code
      after:
        default_browser_return_url: http://127.0.0.1:4455/

    logout:
      after:
        default_browser_return_url: http://127.0.0.1:4455/login

    login:
      lifespan: 10m
      ui_url: http://127.0.0.1:4455/login

    registration:
      lifespan: 10m
      ui_url: http://127.0.0.1:4455/registration
      after:
        password:
          hooks:
            - hook: session
            - hook: show_verification_ui

log:
  level: debug
  format: text

secrets:
  cookie:
    - PLEASE-CHANGE-ME-I-AM-VERY-INSECURE
  cipher:
    - 32-LONG-SECRET-NOT-SECURE-AT-ALL

identity:
  default_schema_id: user
  schemas:
    - id: user
      url: file:///etc/config/kratos/user.schema.json

courier:
  smtp:
    connection_uri: smtps://test:test@mailslurper:1025/?skip_ssl_verify=true

Finally, we add the container setup to the existing docker-compose file, so that Kratos is included in our local deployment.

version: "3.9"
services:
  ...
  kratos:
    image: oryd/kratos:v1.0.0
    container_name: taskmanagementservice-kratos
    depends_on:
      - kratos-migrate
      - mailslurper
    ports:
      - "4433:4433"
      - "4434:4434"
    environment:
      - DSN=sqlite:///var/lib/sqlite/db.sqlite?_fk=true
      - LOG_LEVEL=trace
    command: serve -c /etc/config/kratos/kratos.yml --dev --watch-courier
    volumes:
      - .data/kratos:/var/lib/sqlite/
      - ./kratos.yml:/etc/config/kratos/kratos.yml
      - ./user.schema.json:/etc/config/kratos/user.schema.json
    networks:
      - intranet
  kratos-migrate:
    image: oryd/kratos:v1.0.0
    container_name: taskmanagementservice-kratos-migrate
    environment:
      - DSN=sqlite:///var/lib/sqlite/db.sqlite?_fk=true&mode=rwc
    command: -c /etc/config/kratos/kratos.yml migrate sql -e --yes
    volumes:
      - .data/kratos:/var/lib/sqlite/
      - ./kratos.yml:/etc/config/kratos/kratos.yml
      - ./user.schema.json:/etc/config/kratos/user.schema.json
    networks:
      - intranet
  kratos-selfservice-ui-node:
    image: oryd/kratos-selfservice-ui-node:v1.0.0
    container_name: taskmanagementservice-kratos-selfservice-ui-node
    ports:
      - "4455:4455"
    environment:
      - KRATOS_PUBLIC_URL=http://taskmanagementservice-kratos:4433/
      - KRATOS_BROWSER_URL=http://127.0.0.1:4433/
      - PORT=4455
    networks:
      - intranet
  mailslurper:
    image: oryd/mailslurper:latest-smtps
    container_name: taskmanagementservice-mailslurper
    ports:
      - "4436:4436"
      - "4437:4437"
    networks:
      - intranet
networks:
  intranet:

Important bits to notice in this change are:

• we are adding 4 new containers to our local setup

  • kratos is the container running the Kratos API itself

  • kratos-migrate is a single-command container used for applying SQL migrations the first time the deployment is started, after which the container is no longer used

  • kratos-self-service-ui-node is a pre-built UI for self-service user management provided by the Ory Kratos team themselves - we use this to make user registration easier for the purpose of this tutorial (ideally, we would build our own UI - Kratos is quite flexible when it comes to UI choice)

  • mailslurper is the container that will handle email verification during registration; Kratos will use this as a stub for sending and receiving emails so that we don't have to configure a real email provider

• we are binding the Kratos configuration files defined above to the corresponding locations on the containers where Kratos would expect to find them

• we are instructing Kratos to use SQLite as storage layer

This concludes the changes needed to deploy Kratos locally. The full commit can be found here.

To test the deployment we can use the standard docker-compose build commands we used in the previous blog posts.

To start the deployment and rebuild the task management service container:

docker-compose up --build -d

To stop the deployment:

 docker-compose down

Integration with Kratos API

Now, that we have the skeleton logic in place along with the local deployment setup for Kratos we can integrate the two services. First, we define the interface for the user-related functionalities needed by the task management service:

public interface UserManagementService {
    Optional<User> getUserByAuthToken(String authToken) throws IOException;
}

For now, we only need a single method that accepts an authentication token as input and returns an optional user. The return is optional because the auth token might be invalid or might not correspond to any active user session.

Then, we add a Kratos-based implementation of this interface along with the Kratos client maven dependency:

    ...
    <dependencies>
        ...
        <dependency>
            <groupId>sh.ory.kratos</groupId>
            <artifactId>kratos-client</artifactId>
            <version>0.13.1</version>
        </dependency>
    </dependencies>
    ...

public class KratosWrapper implements UserManagementService {

    private final FrontendApi kratosFrontendApi;

    @Inject
    public KratosWrapper(FrontendApi kratosFrontendApi) {
        this.kratosFrontendApi = kratosFrontendApi;
    }

    public Optional<User> getUserByAuthToken(String authToken) throws IOException {
        Session session;
        try {
            session = kratosFrontendApi.toSession(authToken, null);
        } catch (ApiException e) {
            if (e.getCode() == Response.Status.UNAUTHORIZED.getStatusCode()) {
                return Optional.empty();
            }

            throw new IOException(e);
        }

        if (session == null) {
            return Optional.empty();
        }

        if (session.getActive() == null || !session.getActive()){
            throw new AuthenticationException("Inactive session returned for the given authentication token.");
        }

        return Optional.of(new User(session.getIdentity().getId()));
    }
}

You might notice that the Kratos FrontentApi instance is injected into the constructor which means we need to add a new Guice module that initializes it:

public class KratosModule extends AbstractModule {

    @Provides
    private FrontendApi provideKratosFrontendApi() {
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath(System.getenv("Kratos_Base_Path"));

        return new FrontendApi(apiClient);
    }
}

The base path for the API client we configure through an environment variable - we used the same mechanism for configuring the integration between the task management service and the MongoDB instance in a previous tutorial.

The new environment variable we configure in the docker-compose file used for local deployment:

  ...
  webapp:
    build: .
    container_name: taskmanagementservice-api
    depends_on:
      - "mongo"
      - "kratos"
    environment:
      - MongoDB_URI=mongodb://taskmanagementservice-mongodb:27017
      - Kratos_Base_Path=http://taskmanagementservice-kratos:4433
    ports:
      - "8080:8080"
    networks:
      - intranet 
  ...

To connect all the pieces, we need to also bind the UserManagementService interface to the KratosWrapper implementation in the main Guice application module so that any classes that require an instance of the UserManagementService interface will use an instance of the KratosWrapper class.

public class ApplicationModule extends AbstractModule {

    @Override
    public void configure() {
        bind(TaskManagementRepository.class).to(MongoDBTaskManagementRepository.class).in(Singleton.class);
        bind(UserManagementService.class).to(KratosWrapper.class).in(Singleton.class);

        install(new MongoDBModule());
        install(new KratosModule());
    }

}

The final step is to change the dummy AuthenticationFilter logic we added in the first commit so that it uses the UserManagementService to retrieve a User instance given an authentication token.

@Priority(3)
@Provider
public class AuthenticationFilter implements ContainerRequestFilter {

    private final UserManagementService userManagementService;

    @Inject
    public AuthenticationFilter(UserManagementService userManagementService) {
        this.userManagementService = userManagementService;
    }

    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {
        String authHeader = requestContext.getHeaderString("Authorization");
        if (authHeader == null) {
            return;
        }
        authHeader = authHeader.trim();
        if (!authHeader.startsWith("Bearer")) {
            throw new AuthenticationException("invalid authentication scheme - please use a Bearer token");
        }

        String authToken = authHeader.replaceFirst("Bearer", "").trim();
        Optional<User> user = userManagementService.getUserByAuthToken(authToken);
        user.ifPresent(u -> requestContext.setProperty("user", u));
    }
}

The full commit for this step of the tutorial can be found here.

Testing

Before we start testing, let's re-build the full stack from scratch:

docker-compose down
docker-compose up --build -d

Then, we use the Kratos self-service UI to register a new user by visiting http://127.0.0.1:4455/welcome in the browser.

You will notice that we only need to provide an email address to register because this is what we defined in the user schema. If more fields are added, they will be automatically listed in the registration form we see in this UI.

Choose a username and password and remember them because we will need them later. Keep in mind that Kratos comes in with pre-built password checks by default and won't let you choose a simple password that has already been leaked in data breaches. The email address doesn't matter because emails are only sent locally to mailslurper. For this tutorial I chose:

• test@test as email address

• FMcm6K2Lm9N0KqP as password

After signing up, we should mimic the verification of the email address through mailslurper. This can be done by visiting http://127.0.0.1:4436/ in the browser where you will notice a mailbox-like UI with an email with subject "Please verify your email address"

After opening the email and following the verification link you will be presented with a pre-filled form for finalising the verification.

After finishing verification, we will be automatically logged in to the self-service UI. You can browse the UI further if you'd like to explore Kratos, but the next step for this tutorial is to head to the terminal and login through an API flow (a Kratos abstraction for a user action - https://www.ory.sh/docs/kratos/self-service) so that we receive a session token rather than a session cookie which is what happens if we log in through the browser.

API_LOGIN_FLOW_ID=$(curl -s http://127.0.0.1:4433/self-service/login/api | jq -r '.id')
curl -s -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"identifier": "test@test", "password": "FMcm6K2Lm9N0KqP", "method": "password"}' "http://127.0.0.1:4433/self-service/login?flow=$API_LOGIN_FLOW_ID" | jq -r '.session_token'
ory_st_Q9TNLNgzq9zuucBteAkKXaWubZWOE7wK

The short script above initializes an API login flow, fetches the ID of the flow, then uses it to login with the credentials chosen above and finally, it fetches the session token from the response.

Now that we have a session token, we can use it to send authenticated requests to the task management service API.

curl -i -X POST -H "Authorization: Bearer ory_st_Q9TNLNgzq9zuucBteAkKXaWubZWOE7wK" -H "Content-Type: application/json" -d '{"title": "test_title", "description": "test_description"}' -s http://127.0.0.1:8080/api/tasks
HTTP/1.1 201 
Location: http://127.0.0.1:8080/api/tasks/4b47e790-4a63-43b5-8003-c7b50c5b5f2d
Content-Length: 0
Date: Sun, 27 Aug 2023 07:55:54 GMT

If we then fetch the newly created task, we will see the user ID of the creator.

curl -s http://127.0.0.1:8080/api/tasks/4b47e790-4a63-43b5-8003-c7b50c5b5f2d | jq '.'
{
  "identifier": "4b47e790-4a63-43b5-8003-c7b50c5b5f2d",
  "title": "test_title",
  "description": "test_description",
  "createdBy": "45cdab5b-125d-4d31-a1eb-463b816065f2",
  "createdAt": "2023-08-27T07:55:54.441Z",
  "completed": false
}

We can use the Kratos admin API to check who this user is:

 curl -s "http://127.0.0.1:4434/admin/identities/45cdab5b-125d-4d31-a1eb-463b816065f2" | jq '.'
{
  "id": "45cdab5b-125d-4d31-a1eb-463b816065f2",
  "credentials": {
    "password": {
      "type": "password",
      "identifiers": [
        "test@test"
      ],
      "version": 0,
      "created_at": "2023-08-27T07:37:57.12699Z",
      "updated_at": "2023-08-27T07:53:28.338209Z"
    }
  },
  "schema_id": "user",
  "schema_url": "http://127.0.0.1:4433/schemas/dXNlcg",
  "state": "active",
  "state_changed_at": "2023-08-27T07:37:57.067218753Z",
  "traits": {
    "email": "test@test"
  },
  "verifiable_addresses": [
    {
      "id": "caef9cfd-7b97-43d5-b1cd-1d33facd3869",
      "value": "test@test",
      "verified": true,
      "via": "email",
      "status": "completed",
      "verified_at": "2023-08-27T07:38:29.563302796Z",
      "created_at": "2023-08-27T07:37:57.094576Z",
      "updated_at": "2023-08-27T07:37:57.094576Z"
    }
  ],
  "recovery_addresses": [
    {
      "id": "378e3a1f-a0f4-46c8-8d36-0f8fd8ed192e",
      "value": "test@test",
      "via": "email",
      "created_at": "2023-08-27T07:37:57.113134Z",
      "updated_at": "2023-08-27T07:37:57.113134Z"
    }
  ],
  "metadata_public": null,
  "metadata_admin": null,
  "created_at": "2023-08-27T07:37:57.070219Z",
  "updated_at": "2023-08-27T07:37:57.070219Z"
}

As expected, this user ID corresponds to the user we created earlier as part of this tutorial and with this, our end-to-end manual test is completed.

Summary

To summarize, in this tutorial we added authentication to the task management API by implementing the following changes:

• we added a createdBy reference to the existing Task entity which represents the ID of the user who created the given task

• we added configuration and local deployment setup for Kratos

• we added an authentication filter that parses the Authorization HTTP header and calls Kratos API to convert an authentication token to a User entity

We did not cover the Kratos-related abstractions and how Kratos works in general, but I will be happy to go through this in a separate tutorial. For now, my plan for the next post from this series is to introduce a basic level of authorization. The problem we have with the current state of the API is that every user has access to read and update the tasks created by other users. This will be fixed by introducing access control and letting task creators authorize other users to be able to read their tasks if needed.

As always, feel free to ask any questions or leave feedback in the comments section.

I've been delaying this blog post for a while now because:

• it is not strictly related to software engineering which is my career field

• it always felt as if I am writing about something that is out of my area

However, throughout this year I've shared the idea you are going to read about with a few friends and co-workers - to my surprise, all of them reacted positively and (I hope) one way or another it made their career journey easier. That's why I decided to finally put these thoughts in a blog post which can reach multiple people that might be struggling or getting discouraged or considering giving up on the goals and path they have chosen for themselves - be it a challenging career, a university degree in a complex field of study, an academic research project, etc. While the examples I give are mainly derived from my journey in software engineering, I have a strong feeling that people with different backgrounds will also share my opinion on this and find the analogy beneficial.

The What

We are going to explore what I like to call The Pyramid Analogy of Progress and Development or in short The Pyramid Analogy. Before we dive into it, let's start with a definition of the word analogy from the Cambridge dictionary [1]:

a comparison between things that have similar features, often used to help explain a principle or idea

This definition explains exactly what I will try to do in this post - I want to explain the idea of perceiving studying and self-development (in any field) as an endless endeavour by comparing it with an exploration journey of an infinite pyramid starting from the top with the goal to cover every inch inside the pyramid.

To explain the analogy, let's introduce a game with the following rules:

• we have an infinitely high pyramid

• our starting point is the top of the pyramid

• the pyramid is broken down into layers which represent different levels of the game - the more layers we cover, the more we progress

• we can only jump from one layer to the next when we have explored the entire surface of the current layer

Here is a diagram that visualizes the game:

The first thing we can notice is that as with many other games the more we progress, the more difficult it becomes to move to the next level. This is because each time we move deeper along the height of the pyramid, we get to a surface area that is larger than the one we have just covered. The second conclusion we can also immediately notice is that this is an infinite game - a game with no end. We can keep making progress by moving from one surface to the next, but because the pyramid is infinitely high, we can never reach the bottom surface. Yet, everyone that has played a similar game knows how addictive it is to keep levelling up and exploring new territories. In the beginning, making progress seems easy. At some point, we start struggling to pass to the next level. Do we feel discouraged when we fail multiple times? Obviously! Do we give up? Of course not! We just keep trying different ways until we succeed - we know we can succeed because otherwise, we wouldn't have been able to pass the previous levels of the game which in this case are the previous layers of the pyramid.

By now, I assume this analogy already sounds familiar. To me, this is exactly how it feels every time I put my focus on a particular goal. In the beginning, it seems easy, my motivation is high, and I think I can achieve the world. The more I progress, the harder it gets. I start feeling discouraged, I want to give up, impostor syndrome kicks in, and motivation is at its lowest levels. In these situations, what we usually fail to remember and understand is that the reason it feels harder is not that we are incompetent or lack the skills to move forward, but rather the fact that we have progressed so deep in the pyramid that the current layer we need to explore is bigger than anything we have seen so far. If we were playing the pyramid exploration game, what we would have done is find a different strategy to pass the new layer - in real life that would mean changing our studying strategy, changing the way we approach our tasks at work, trying out different hacks to be more focused and productive, practising our communication skills, reading more, etc.

Another critical rule of the game that we usually forget in real life is that we cannot skip layers - we can't just jump from layer 1 to layer 10. We need to cover the areas of layer 1, layer 2, layer 3 and so on until we finally reach layer 10. I assume this also sounds familiar to all of us. Frequently, we tend to forget that we cannot skip steps. You cannot just take up a new hobby and become a master of it without enduring the struggles of consistent practice. You cannot just start a new job and expect to learn everything from the company's domain within a month. You cannot demand a promotion without proving your worth. You cannot start a company and turn it into a unicorn startup [2] without putting in the hard work. All of these are real-life examples of our desires to skip layers in the pyramid game analogy.

Last but not least, another comparison we can draw from this analogy is the infinite nature of the pyramid game. Just as you can keep playing the game and moving from one layer to the next till infinity, the same is true when you start a new career or decide to explore a new area of study or commence anything related to your self-development. We have to remember - it is always an infinite game which gets harder as we progress. However, it is critical to acknowledge that just because the game doesn't end and there will always be something new to learn or to improve, it doesn't mean that we should not pursue the journey. Just the opposite, its infinite nature is what makes it so exciting and what keeps people engaged and helps them overcome the continuous struggle that's part of progressing in the pyramid. As many other (much more successful than me) people like to say - you have to fall in love with the journey rather than the destination. In my experience, the easiest way to achieve that mindset is to embrace The Pyramid Analogy.

The How

So how can all of this help you? It's all about changing the perspective we have on challenges encountered during our journey to success for a particular goal. First of all, let's face it, it's inevitable - at a certain point in time, we are all going to face problems, feel down and discouraged, and think of giving up. In these situations, it's easy to go into a spiral of negative thinking where a single negative thought triggers many more, and from there on the domino-effect kicks in. This is when The Pyramid Analogy has helped immensely in my personal life - it helped me redirect my mindset in the right direction.

Let me explain the thought process. The pyramid game showed us that the reason overcoming a particular layer turns out to be challenging is the fact that we have covered many other smaller layers before that. So applying this logic in real life, we wouldn't even be facing a particular challenge if we haven't faced and successfully overcome many others before that. So instead of letting our minds go into the spiral of negative thinking, we can re-focus on all the wins we've had in the past - yes, smaller in size in comparison to what we want to achieve right now, but at that time being the biggest win we could get. We can also embrace the fact that because we are covering a wider area in the pyramid right now, it is only logical we would need to put much more effort into it. Just as it is with other games, we search for different approaches to progress to the next level. The motivation and excitement come from the fact that we can keep progressing till infinity - there is always something new we need to learn or another challenge we have to face.

The Examples

To convince you that this is not just a big-words article, I'd like to also present a couple of examples from my personal life (there are plenty of other examples, but I do not want this post to be a this-was-my-life essay):

• Studying in university - for every single subject I decided to put my focus on I could see a clear pyramid analogy; at first, everything seemed easy, but the more you progress, the harder it gets to grasp the new concepts and theories

• Software engineering career - probably the most applicable example is my career development in software engineering at The IT Innovation Centre and Amazon. Not only did I need to acquire more skills to keep progressing in my career, but I also had to continuously learn more and more about the domain of the project I was working on at a given point in time. For both companies, I was experiencing the same pattern - with each new layer of domain knowledge I passed, I only realized how little I knew and that the new layer I had to cover was much wider.

In both examples, I could easily let myself drown in negativity, but instead, I chose to focus on what I did to reach the current level, and embrace that it's only natural for the current challenge to be more difficult - I was covering a larger surface area in the pyramid in comparison to what I have seen before.

The Conclusions

If we have to summarize The Pyramid Analogy, I would list the following key points:

• Any long-term goals we have can be modelled as an infinite pyramid which needs to be covered in a top-down approach.

• As we progress in the infinite pyramid, it is only natural that it's going to feel more challenging - the surface area at a given layer is larger than the areas covered in previous layers.

• The journey never ends - we will always have a new surface to explore as we go along the height of the pyramid.

To use this analogy to our advantage, we have to remember that:

• We would have never reached a given layer if we haven't successfully passed other layers before that.

• To cover new layers of the pyramid we have to be flexible to changes and always adapt our approach to the current challenge - it's always something we haven't seen, therefore, we cannot expect previous approaches to just work like magic.

• Each new layer is the key to much more exciting challenges and opportunities.

I sincerely hope that reading this article will to some extent help you continue your personal journey to success. I would also love to hear any comments you have about the idea presented in this post or examples of your own which resonate with The Pyramid Analogy.

The References

[1] https://dictionary.cambridge.org/dictionary/english/analogy

[2] https://en.wikipedia.org/wiki/Unicorn_(finance)

This post is a follow-up to the last two tutorials for building a Java REST API (Task Management Service) and integrating it with a MongoDB database:

• https://blog.teonisoftware.com/step-by-step-tutorial-for-building-a-rest-api-in-java

• https://blog.teonisoftware.com/integrating-a-java-rest-api-with-a-database

I've decided to add logging and monitoring functionalities to be able to track the performance of the API. Metrics and logs are two critical parts of achieving operational stability for a given software service. While they serve slightly different purposes and can be used independently, it's usually the combination of the two that gives the greatest benefit when it comes to preventing, troubleshooting and resolving service outages. In this tutorial, we are going to use:

• Log4j2 - a Java software framework that alleviates the process of adding logging functionality in a given piece of software

• Prometheus - a set of applications used for storing, querying and visualizing real-time metrics

Current State

In the current setup, the local deployment consists of two containers:

• one for running the service for managing TODO/task items

• one for running the Mongo DB instance used as the storage mechanism for the API

Docker is used as the container runtime environment and docker-compose is used to orchestrate the multi-container deployment.

Target State

What we want to achieve at the end of this tutorial is the diagram below. The green colour is used to indicate a new component or piece of software.

As we can see, there are 3 major changes:

• A log file where the Task Management Service is going to write information about events, e.g. whenever a new request was processed

• A new API endpoint that will expose Prometheus-format metrics indicating the performance of the Task Management Service, e.g. request latency (how much time it took the service to process a given request)

• A new container that runs the Prometheus server as well as a Prometheus Job that periodically pulls metrics from the Task Management Service

Adding Logs

We start this tutorial by adding logs to the API.

Configuring Log4j2

The first step is to add Log4j as a dependency in the Maven POM file (notice that we are using Log4j v2 which is why this post is referring to Log4j2 instead of its predecessor library Log4j):

  <dependencies>
    ...
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
      <version>2.13.0</version>
    </dependency>
    <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <version>2.13.0</version>
    </dependency>
    ...
  </dependencies>

We also need a special log4j2 properties file which the framework uses to configure the logger instance we need. For this service, we use a very simple config which creates a logger that writes the messages to a file. Since this is not a Log4j-specific tutorial, for details about the config syntax or semantics please refer to the official Log4j documentation

# logging level and dest for internal events within log4j2
status = error
dest = err
# config name
name = ServiceLogConfig

# file appender
appender.file.type = File
appender.file.name = FileLog
appender.file.fileName = /var/log/task-management-service/service.log
appender.file.layout.type = PatternLayout
appender.file.layout.pattern = %d %p %C [%t] %m%n

# service-specific logger (the name should be the root package path of all classes that will use this logger)
logger.service.name = taskmanagement
logger.service.level = info
# linking the service-specific logger to the file appender
logger.service.appenderRefs = file
logger.service.appenderRef.file.ref = FileLog

The full commit for this step can be found here.

Writing logs

Now that we have Log4j2 configured we can start logging messages from within the service. For example, we can override the `toString()` method of the Task class and log a message whenever a new task is created that would show us the auto-generated ID of the new task:

public class Task {
    ...
    @Override
    public String toString() {
        return "Task{" +
                "identifier='" + identifier + '\'' +
                ", title='" + title + '\'' +
                ", description='" + description + '\'' +
                ", createdAt=" + createdAt +
                ", completed=" + completed +
                '}';
    }
    ...
}

public class TaskManagementService {

    // get a logger instance for this class
    private static final Logger LOGGER = LogManager.getLogger(TaskManagementService.class);

    ...

    public Task create(String title, String description)  {
        Task task = Task.builder(title, description).build();

        repository.save(task);

        // log an info message for each new task that was created
        LOGGER.info("Successfully created new task {}", task);

        return task;
    }
...
}

The full commit for this step can be found here.

Another useful thing we can log is a message for each new API request that is sent to the service - the message will contain the request method, the request URI, the response status code and the processing time of the request. To achieve this, we need a LoggingFilter class that implements both the container request filter interface and the container response filter interface:

@Provider
@PreMatching
public class LoggingFilter implements ContainerRequestFilter, ContainerResponseFilter {

    private static final Logger LOGGER = LogManager.getLogger(LoggingFilter.class);

    @Override
    public void filter(ContainerRequestContext requestContext) {
        long processingStartTime = Instant.now().toEpochMilli();
        requestContext.setProperty("requestProcessingStartTime", processingStartTime);
    }

    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext) {
        long processingStartTime = (long) requestContext.getProperty("requestProcessingStartTime");
        long processingEndTime = Instant.now().toEpochMilli();
        long processingLatency = processingEndTime - processingStartTime;

        LOGGER.info("{} {} {} {}ms",
                requestContext.getMethod(),
                requestContext.getUriInfo().getRequestUri().getPath(),
                responseContext.getStatus(),
                processingLatency);
    }
}

The first filter method captures the request before it has been processed by a resource class and records the request processing start time. The second filter method captures the request after it has been processed and calculates how many milliseconds it took the service to process the request. It is important to note that we use the @PreMatching annotation to ensure that the filter is executed even when the Jersey framework doesn't find an appropriate resource class that corresponds to the request URI (i.e. whenever we have a 404 response from the service). As with other provider classes we used in the previous tutorials, we bind the LoggingFilter in the application config:

@ApplicationPath("/api")
public class ApplicationConfig extends ResourceConfig {

    @Inject
    public ApplicationConfig(ServiceLocator serviceLocator) {
        ...
        register(LoggingFilter.class);
        ...
    }

}

The full commit for this step can be found here.

Inspecting Logs

To test that the service is logging messages, we can inspect the log file we configured in the log4j2 config file. First, we start the local deployment of the application and send a couple of test requests to create new tasks.

docker-compose up --build -d

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title-1\", \"description\":\"description\"}" "http://localhost:8080/api/tasks" 
HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/9e3ce938-1206-480d-b84a-0f782eaeb0b4
Content-Length: 0
Date: Sat, 17 Dec 2022 10:46:57 GMT

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title-2\", \"description\":\"description\"}" "http://localhost:8080/api/tasks" 
HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/ccdc375a-a278-4416-826d-62cbbd723b42
Content-Length: 0
Date: Sat, 17 Dec 2022 10:47:09 GMT

Then, we inspect the log file in the docker container using the docker exec command.

docker exec -t taskmanagementservice_api sh -c "cat /var/log/task-management-service/service.log"

2022-12-17 10:46:57,143 INFO taskmanagement.service.TaskManagementService [http-nio-8080-exec-1] Successfully created new task Task{identifier='9e3ce938-1206-480d-b84a-0f782eaeb0b4', title='test-title-1', description='description', createdAt=2022-12-17T10:46:57.100681Z, completed=false}

2022-12-17 10:46:57,156 INFO taskmanagement.api.LoggingFilter [http-nio-8080-exec-1] POST /api/tasks 201 164ms

2022-12-17 10:47:09,249 INFO taskmanagement.service.TaskManagementService [http-nio-8080-exec-3] Successfully created new task Task{identifier='ccdc375a-a278-4416-826d-62cbbd723b42', title='test-title-2', description='description', createdAt=2022-12-17T10:47:09.244510Z, completed=false}

2022-12-17 10:47:09,250 INFO taskmanagement.api.LoggingFilter [http-nio-8080-exec-3] POST /api/tasks 201 8ms

As we can see, for each request we have two messages:

• one from the TaskManagementService class which indicates the creation of a new task

• one from the LoggingFilter showing the response status code and request processing time

Adding Metrics

The next topic of this tutorial is adding metrics to our API. This is a more complex topic, but I tried to bring it down to a few small and easily digestible steps.

Now some background information on Prometheus. It consists of many components of which a major one is the Prometheus server. This component is responsible for scraping, storing and querying the metrics data. For this tutorial, we are going to run the Prometheus server inside a new Docker container. When it comes to metrics data collection, Prometheus follows an HTTP pull model or in other words, the Prometheus server periodically queries other applications for their metrics data. On a high level, this is how it works:

• We configure jobs on the Prometheus server.

• Each job is responsible for collecting the metrics from a particular piece of software (e.g. Nginx)

• Each job can query multiple targets (e.g. multiple hosts running Nginx)

• The query itself represents a GET HTTP call to each target using the URL path /metrics (this is configurable and can be changed for individual jobs)

• If needed different authorization mechanisms can be used in the HTTP call - e.g. providing a Bearer token

For more Prometheus-specific information, please refer to the overview documentation.

Prometheus Container Setup

The first step for integration with Prometheus is to include a Prometheus container in the docker-compose deployment file:

  prometheus:
    image: "prom/prometheus:v2.40.7"
    container_name: taskmanagementservice_prometheus
    volumes:
      - .data/prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

Two key points in the configuration above:

• We mount a persistent volume to the Prometheus container so that metrics are not lost when the container crashes or is restarted - any data stored in /prometheus (default location where Prometheus stores data) on the container will be stored under .data/prometheus (relative to the project root folder) on your local machine.

• We do the same for the prometheus.yml config file. /etc/prometheus/prometheus.yml is the default location where the Prometheus server will look for a configuration file on startup.

As for the Prometheus config file itself, for now, we are going to use a very simple config that instructs Prometheus to scrape itself (this means it will query its own /metrics API endpoint). The scrape interval for all jobs is set to 15 seconds.

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'prometheus'

    static_configs:
      - targets: ['localhost:9090']

The full commit for this step can be found here.

Visualizing Prometheus Metrics

In a production environment, most likely we would have been using a more advanced dashboarding solution (e.g. Grafana) to visualize metrics. However, in this case, we are going to use the Prometheus server built-in expression browser. One metric that Prometheus exposes about itself is called prometheus_http_requests_total and it represents a counter of the number of HTTP requests sent to the Prometheus server broken down by status code, URL path, etc. An example graph for this metric can be seen by visiting this URL in your browser (assuming the local deployment is up and running).

What this graph represents is the counter for successful requests sent to the /metrics URL path. As expected, this is a continuously increasing graph because the metrics endpoint is continuously queried by the job we configured for collecting metrics from the Prometheus server itself.

Implementing Service Metrics API Endpoint

The next step is to implement a metrics API endpoint in the Task Management Service. This endpoint will be queried by a Prometheus metrics collection job that we will configure later.

We start by adding a dependency in the POM file for the Prometheus client library:

  <dependencies>
    ...
    <dependency>
      <groupId>io.prometheus</groupId>
      <artifactId>simpleclient_httpserver</artifactId>
      <version>0.16.0</version>
    </dependency>
    ...
  </dependencies>

Then, we implement the metrics API resource class:

@Path("/metrics")
public class MetricsResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String metrics() throws IOException {
        StringWriter writer = new StringWriter();

        TextFormat.write004(writer, CollectorRegistry.defaultRegistry.metricFamilySamples());

        return writer.toString();
    }

}

It is worth mentioning that throughout this implementation we are going to use the default metrics collectors registry which is sufficient for our use case and also makes the implementation much simpler. As we can see in the code above, the implementation of the endpoint is simply calling a method on the default registry and returning the response as plain text. The Prometheus client library outputs the response in the format expected by the Prometheus server job. (We will see what the format looks like during testing).

Next, we implement the metrics filter (the class responsible for populating metrics in the default registry), but before that, we need to make two small changes in the logging filter we implemented earlier:

• adding a priority annotation to define the order in which the filters are executed (the lower the number, the higher the priority)

• setting a request context property - requestProcessingTime - to preserve the request processing time so that it can also be used in the metrics filter

@Priority(2)
@Provider
@PreMatching
public class LoggingFilter implements ContainerRequestFilter, ContainerResponseFilter {
    ...
    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext) {
        ...
        // save the request processing time so that it can be used in the metrics filter
        requestContext.setProperty("requestProcessingTime", processingLatency);
        ...
    }
}

As for the metrics filter, this is what it looks like:

@Priority(1)
@Provider
public class MetricsFilter implements ContainerResponseFilter {

    private static final String[] LABELS = new String[]{
            "requestMethod",
            "uriPath",
            "responseCode"
    };

    private static final Histogram requestLatencyHistogram = Histogram.build()
            .name("task_management_service_requests_latency")
            .labelNames(LABELS)
            .buckets(5, 25, 50, 75, 100, 500, 1000, 5000, 10000)
            .help("Request latency in milli-seconds.")
            .register();

    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext) {
        String[] labelsValues = new String[3];

        String requestMethod = requestContext.getMethod();
        labelsValues[0] = requestMethod;

        String uriPath = requestContext.getUriInfo().getRequestUri().getPath();
        labelsValues[1] = uriPath;

        int responseCode = responseContext.getStatus();
        labelsValues[2] = Integer.toString(responseCode);

        long processingTime = (long) requestContext.getProperty("requestProcessingTime");

        requestLatencyHistogram
                .labels(labelsValues)
                .observe(processingTime);
    }
}

Key points here are:

• We use priority with value 1 which is less than the value of the logging filter priority - what this means is that the order of execution would be the following:

  1. request filter method from MetricsFilter class (if one exists, in our case there isn't one)

  2. request filter method from LoggingFilter class

  3. response filter method from LoggingFilter class

  4. response filter method from MetricsFilter class

• We rely on the fact that the logging filter's execution was successful so that the request processing time property can be extracted from the request context

• We use a histogram registered in the default registry to collect the latency metric - for more information on histograms, refer to the documentation

Finally, we need to register both the MetricsFilter class and the MetricsResource class in the application API config:

@ApplicationPath("/api")
public class ApplicationConfig extends ResourceConfig {

    @Inject
    public ApplicationConfig(ServiceLocator serviceLocator) {
        ...
        register(MetricsResource.class);
        ...
        register(MetricsFilter.class);
        ...
    }

}

Now, we can test the new endpoint using curl. For a fresh deployment, the first time we query the endpoint we get this response:

curl -i -X GET  "http://localhost:8080/api/metrics" 
HTTP/1.1 200 
Content-Type: text/plain
Content-Length: 140
Date: Sat, 17 Dec 2022 17:10:02 GMT

# HELP task_management_service_requests_latency Request latency in milli-seconds.
# TYPE task_management_service_requests_latency histogram

This is because this request is the first one processed by the task management service. Therefore, no metrics have been collected yet. If we repeat the same request, we get the following:

curl -i -X GET  "http://localhost:8080/api/metrics" 
HTTP/1.1 200 
Content-Type: text/plain
Content-Length: 1918
Date: Sat, 17 Dec 2022 17:11:25 GMT

# HELP task_management_service_requests_latency Request latency in milli-seconds.
# TYPE task_management_service_requests_latency histogram
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="5.0",} 0.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="25.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="50.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="75.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="100.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="500.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="1000.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="5000.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="10000.0",} 1.0
task_management_service_requests_latency_bucket{requestMethod="GET",uriPath="/api/metrics",responseCode="200",le="+Inf",} 1.0
task_management_service_requests_latency_count{requestMethod="GET",uriPath="/api/metrics",responseCode="200",} 1.0
task_management_service_requests_latency_sum{requestMethod="GET",uriPath="/api/metrics",responseCode="200",} 7.0
# HELP task_management_service_requests_latency_created Request latency in milli-seconds.
# TYPE task_management_service_requests_latency_created gauge
task_management_service_requests_latency_created{requestMethod="GET",uriPath="/api/metrics",responseCode="200",} 1.671297002185E9

It's visible that this is a very robust response because of the multiple histogram buckets. However, all it is saying is that there was one processed request in total (the first curl request we sent) and it took 7ms to process it (the histogram works based on a list of buckets and a metric is recorded in all buckets with a value bigger than the metric value - that's why only the first bucket with value 5 still has a count of 0)

We can also confirm the above by looking at the log file again which shows that the request took 7ms to process:

docker exec -t taskmanagementservice_api sh -c "cat /var/log/task-management-service/service.log"
2022-12-17 17:10:02,182 INFO taskmanagement.api.LoggingFilter [http-nio-8080-exec-1] GET /api/metrics 200 7ms

Now we need to integrate Prometheus with this endpoint so that service metrics are continuously collected. This can be achieved by configuring a new job in the Prometheus config file:

...
scrape_configs: 
  - job_name: 'task-management-service'

    metrics_path: /api/metrics

    static_configs:
      - targets: ['localhost:8080']
...

The full commit for this step can be found here.

Finally, we reset the deployment so that the new changes can take effect:

docker-compose down
docker-compose up --build -d

Visualizing Service Metrics

To see the service-specific metrics visualized in the Prometheus expression browser, we need to send a few test requests first:

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title-1\", \"description\":\"description\"}" "http://localhost:8080/api/tasks"
HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/ae33f988-0260-498b-b9c6-51d52250ffce
Content-Length: 0
Date: Sat, 17 Dec 2022 17:56:46 GMT

curl -i -X GET "http://localhost:8080/api/tasks/ae33f988-0260-498b-b9c6-51d52250ffce"
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 161
Date: Sat, 17 Dec 2022 17:57:17 GMT

{"identifier":"ae33f988-0260-498b-b9c6-51d52250ffce","title":"test-title-1","description":"description","createdAt":"2022-12-17T17:56:46.856Z","completed":false}  

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title-1\", \"description\":\"description\"}" "http://localhost:8080/api/tasks"
HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/b373370c-1abe-410f-a646-d1bab895cd96
Content-Length: 0
Date: Sat, 17 Dec 2022 17:59:18 GMT

curl -i -X GET "http://localhost:8080/api/tasks/b373370c-1abe-410f-a646-d1bab895cd96"
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 161
Date: Sat, 17 Dec 2022 17:59:30 GMT

{"identifier":"b373370c-1abe-410f-a646-d1bab895cd96","title":"test-title-1","description":"description","createdAt":"2022-12-17T17:59:18.181Z","completed":false}

After waiting for a minute, we should be able to see the new metrics in the Prometheus expression browser by going to http://localhost:9090/graph and searching for the task_management_service_requests_latency_count metric. In the table view we can see the number of processed requests broken down by URI path, request method and response status code:

If you are interested in playing around with the new metric, in the Prometheus histograms documentation you will find other queries that can be used to produce valuable performance graphs.

Summary

In conclusion, as part of this tutorial, we have implemented two major operational stability improvements in the task management service API:

1. file-based logging functionality using log4j2 which helped us:

   • log a message whenever a new task is created so that we can easily find the auto-generated UUID for the new task

   • log a message whenever a new request is processed so that we can easily find the response code for the given request as well the time it took to process the request

2. metrics functionality using Prometheus which helped us:

   • emit metrics for the latency and count of processed API requests broken down by URI path, request method and response status code

We also visualized the new metrics in the Prometheus expression browser. Ideally, we can integrate Grafana with Prometheus so that these metrics are included in a proper monitoring dashboard. Let me know if you would like to see a separate tutorial on this or if you have any questions regarding the topics explored in this blog post.

This article is a follow-up to my last tutorial on building a fully functional Java REST API for managing TODO tasks. For simplicity, last time we used an in-memory database as an implementation of the storage interface defined by our business logic. It is clear that this solution is not feasible for a production-ready API mainly because:

• we will lose the stored tasks every time we stop the application

• different application instances will not be able to share memory - in other words, if we horizontally scale up our service by using two servers - A and B, then tasks created through server A will not be seen by tasks created through server B.

This is illustrated in the diagram below:

In this tutorial I want to demonstrate how we can integrate the API we built as part of the previous article with a very famous open-source non-relational database, namely MongoDB. This means changing the diagram above to the following:

For the purpose of simplicity, I chose MongoDB, but technically we could have also chosen a relational database such as PostgreSQL. If we were to choose between the two DBs, we would need to know a bit more about the software requirements of our service - things like:

• scalability - how much is the application expected to grow in the future

• expected traffic pattern - how many clients are going to use the service, what request rate they will use, read vs write ratio, etc.

• access patterns - do we have a well-defined access pattern requested by our business stakeholders or do we need an approach that allows for general search queries

The API specification is not enough on its own to make this decision, but for the purpose of this tutorial, we can go ahead and use MongoDB.

Current State

A quick reminder of what we built before is given below:

• a repository interface defining the functionality our business logic requires for storing and retrieving tasks

public interface TaskManagementRepository {

    void save(Task task);

    List<Task> getAll();

    Optional<Task> get(String taskID);

    void delete(String taskID);
}

• an in-memory DB implementation of the repository interface that uses a hash map to store and retrieve tasks

public class InMemoryTaskManagementRepository implements TaskManagementRepository {

    private Map<String, Task> tasks = new HashMap<>();

    @Override
    public void save(Task task) {
        tasks.put(task.getIdentifier(), task);
    }

    @Override
    public List<Task> getAll() {
        return tasks.values().stream()
                .collect(Collectors.toUnmodifiableList());
    }

    @Override
    public Optional<Task> get(String taskID) {
        return Optional.ofNullable(tasks.get(taskID));
    }

    @Override
    public void delete(String taskID) {
        tasks.remove(taskID);
    }

}

• a Guice binding that ensures every piece of business logic that needs to use a TaskManagementRepository instance will use the same InMemoryTaskManagementRepository instance

public class ApplicationModule extends AbstractModule {

    @Override
    public void configure() {
        bind(TaskManagementRepository.class).to(InMemoryTaskManagementRepository.class).in(Singleton.class);
    }

}

Target State

The goal of this tutorial is to implement a new class called MongoDBTaskManagementRepository which will be an implementation of the repository interface that uses MongoDB for persistent storage.

We are going to have the DB running as a separate Docker container. Therefore, we will now have an application made of two containers - the service container and the DB container. We will use Docker Compose to manage the multi-container application as a single entity. Keep in mind that this is not a Docker-focused tutorial, so the focus won't be on explaining best practices for setting up a database with Docker or how to use Docker and Docker Compose in general. Feel free to leave a comment if you would like to see a separate article for this.

Database Integration

MongoDB Container Setup

We start by pulling a MongoDB Docker image and setting up our Docker Compose file to start two containers - one for the service itself and one for a MongoDB instance:

docker pull mongo:5.0.9

The Docker Compose file is given below. Notice that we mount a persistent volume to the MongoDB container since we don't want the data to be wiped out whenever the container crashes or is rebuilt). What this means is that any data stored in /data/db on the MongoDB container will be stored under data/mongo (relative to the project root folder) on your laptop. Keep in mind that /data/db is where the MongoDB container stores data by default.

version: "3.9"
services:
  mongo:
    image: "mongo:5.0.9"
    volumes:
      - .data/mongo:/data/db
  webapp:
    build: .
    depends_on:
      - "mongo"
    ports:
      - "8080:8080"

To start the application, we run docker-compose up --build -d which effectively does three things:

• creates a container running the MongoDB image - using the default MongoDB port 27017 for connections

• re-builds the image for our REST API and creates a container running the service - the container will have port 8080 exposed so that you can connect from your laptop to the API

• creates a virtual network connecting the two containers

To stop the application and clean up the resources (containers and network), run docker-compose down.

The full commit for this step can be found here.

Repository Interface Implementation

Now that we have a MongoDB instance running, we need to create a new class - MongoDBTaskManagementRepository - that will implement the repository interface.

public class MongoDBTaskManagementRepository implements TaskManagementRepository {

    private final MongoCollection<MongoDBTask> tasksCollection;

    @Inject
    public MongoDBTaskManagementRepository(MongoCollection<MongoDBTask> tasksCollection) {
        this.tasksCollection = tasksCollection;
    }

    @Override
    public void save(Task task) {
        MongoDBTask mongoDBTask = toMongoDBTask(task);
        ReplaceOptions replaceOptions = new ReplaceOptions()
                .upsert(true);
        tasksCollection.replaceOne(eq("_id", task.getIdentifier()), mongoDBTask, replaceOptions);
    }

    @Override
    public List<Task> getAll() {
        FindIterable<MongoDBTask> mongoDBTasks = tasksCollection.find();

        List<Task> tasks = new ArrayList<>();
        for (MongoDBTask mongoDBTask: mongoDBTasks) {
            tasks.add(fromMongoDBTask(mongoDBTask));
        }

        return tasks;
    }

    @Override
    public Optional<Task> get(String taskID) {
        Optional<MongoDBTask> mongoDBTask = Optional.ofNullable(
                tasksCollection.find(eq("_id", taskID)).first());

        return mongoDBTask.map(this::fromMongoDBTask);
    }

    @Override
    public void delete(String taskID) {
        Document taskIDFilter = new Document("_id", taskID);
        tasksCollection.deleteOne(taskIDFilter);
    }

    private Task fromMongoDBTask(MongoDBTask mongoDBTask) {
        return Task.builder(mongoDBTask.getTitle(), mongoDBTask.getDescription())
                .withIdentifier(mongoDBTask.getIdentifier())
                .withCompleted(mongoDBTask.isCompleted())
                .withCreatedAt(Instant.ofEpochMilli(mongoDBTask.getCreatedAt()))
                .build();
    }

    private MongoDBTask toMongoDBTask(Task task) {
        MongoDBTask mongoDBTask = new MongoDBTask();
        mongoDBTask.setIdentifier(task.getIdentifier());
        mongoDBTask.setTitle(task.getTitle());
        mongoDBTask.setDescription(task.getDescription());
        mongoDBTask.setCreatedAt(task.getCreatedAt().toEpochMilli());
        mongoDBTask.setCompleted(task.isCompleted());

        return mongoDBTask;
    }

    private static class MongoDBTask {
        @BsonProperty("_id")
        private String identifier;

        private String title;

        private String description;

        @BsonProperty("created_at")
        private long createdAt;

        private boolean completed;
        ...
    }
...
}

Given that this is not a MongoDB-specific tutorial, I skipped a few implementation details around the Mongo DB Java driver, but in essence, we are using a very basic implementation that maps the internal MongoDBTask POJO to a Mongo DB document. For more details, see the official tutorial.

The full commit for this step can be found here.

Binding Everything Together

You might have noticed that the MongoDB repository implementation relies on a MongoCollection<MongoDBTask> instance to be injected. This class is an abstraction for interacting with an actual MongoDB collection. In this section, we will write the code for connecting to the database and binding an instance of this class. Since we are using Guice for dependency injection, we will encapsulate this logic into its own Guice module and then use the new module in the main application module.

public class MongoDBModule extends AbstractModule {

    @Provides
    private MongoCollection<MongoDBTaskManagementRepository.MongoDBTask> provideMongoCollection() {
        ConnectionString connectionString = new ConnectionString(System.getenv("MongoDB_URI"));

        CodecRegistry pojoCodecRegistry = fromProviders(PojoCodecProvider.builder().automatic(true).build());
        CodecRegistry codecRegistry = fromRegistries(MongoClientSettings.getDefaultCodecRegistry(), pojoCodecRegistry);

        MongoClientSettings mongoClientSettings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .codecRegistry(codecRegistry)
                .build();

        MongoClient mongoClient = MongoClients.create(mongoClientSettings);
        MongoDatabase mongoDatabase = mongoClient.getDatabase("tasks_management_db");
        return mongoDatabase.getCollection("tasks", MongoDBTaskManagementRepository.MongoDBTask.class);
    }
}

To use this new module, we need to install it in our main application module and change the binding to use the MongoDB repository implementation:

public class ApplicationModule extends AbstractModule {

    @Override
    public void configure() {
        bind(TaskManagementRepository.class).to(MongoDBTaskManagementRepository.class).in(Singleton.class);

        install(new MongoDBModule());
    }

}

You can see in the MongoDB module that we are using a database with name tasks_management_db and a collection with name tasks but we never actually created these. The reason is that MongoDB will automatically create both the database and the collection as soon as we insert the first document (when we create the first task through our API).

The final piece for binding everything together is to configure the MongoDB_URI environment variable used for connecting to the database in the task management service container. This can be done through the Docker Compose file:

version: "3.9"
services:
  webapp:
    ...
    environment:
      - MongoDB_URI=mongodb://taskmanagementservice_mongo_1:27017
    ...

The URI is built based on the default port the MongoDB container uses and the default hostname convention Docker Compose uses when building containers.

The full commit for this step can be found here.

EDIT: After initially writing this blog post, docker-compose changed the default container naming convention which resulted in the MongoDB container being named taskmanagementservice-mongo-1 instead of taskmanagementservice_mongo_1. That's why an additional code change was added to ensure the container names are fixed and the deployment still works:

version: "3.9"
services:
  mongo:
    image: "mongo:5.0.9"
    container_name: taskmanagementservice_mongodb
    volumes:
      - .data/mongo:/data/db
  webapp:
    build: .
    container_name: taskmanagementservice_api
    depends_on:
      - "mongo"
    environment:
      - MongoDB_URI=mongodb://taskmanagementservice_mongodb:27017
    ports:
      - "8080:8080"

The full commit for this change can be found here.

Testing The Service

Before we start testing, let's re-build the full stack from scratch:

docker-compose down
docker-compose up --build -d

Now, both the service and MongoDB should be up and running. We will once again use curl to test the CRUD API (ideally these manual tests should be automated as integration tests but we will leave that for another article where we focus on testing):

• creating a few tasks

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title\", \"description\":\"description\"}" "http://localhost:8080/api/tasks" 

HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/cb06d6a1-960b-47eb-b44b-de0b01303020
Content-Length: 0
Date: Fri, 29 Jul 2022 09:20:25 GMT

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title\", \"description\":\"description\"}" "http://localhost:8080/api/tasks" 

HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/3c4c7a7d-b680-4be5-9dd4-51d02225a700
Content-Length: 0
Date: Fri, 29 Jul 2022 09:20:32 GMT

• retrieving a task

curl -i -X GET "http://localhost:8080/api/tasks/cb06d6a1-960b-47eb-b44b-de0b01303020"

HTTP/1.1 200 
Content-Type: application/json
Content-Length: 159
Date: Fri, 29 Jul 2022 09:21:04 GMT

{"identifier":"cb06d6a1-960b-47eb-b44b-de0b01303020","title":"test-title","description":"description","createdAt":"2022-07-29T09:20:25.410Z","completed":false}

• retrieving a non-existing task

curl -i -X GET "http://localhost:8080/api/tasks/random-task-id-123"

HTTP/1.1 404 
Content-Type: application/json
Content-Length: 81
Date: Fri, 29 Jul 2022 09:21:19 GMT

{"message":"Task with the given identifier cannot be found - random-task-id-123"}

• retrieving all tasks

curl -i -X GET "http://localhost:8080/api/tasks" 

HTTP/1.1 200 
Content-Type: application/json
Content-Length: 321
Date: Fri, 29 Jul 2022 09:21:30 GMT

[{"identifier":"cb06d6a1-960b-47eb-b44b-de0b01303020","title":"test-title","description":"description","createdAt":"2022-07-29T09:20:25.410Z","completed":false},{"identifier":"3c4c7a7d-b680-4be5-9dd4-51d02225a700","title":"test-title","description":"description","createdAt":"2022-07-29T09:20:32.851Z","completed":false}]

• deleting a task

curl -i -X DELETE "http://localhost:8080/api/tasks/3c4c7a7d-b680-4be5-9dd4-51d02225a700"                             

HTTP/1.1 204 
Date: Fri, 29 Jul 2022 09:22:11 GMT

• patching a task

curl -i -X PATCH -H "Content-Type:application/json" -d "{\"completed\": true, \"title\": \"new-title\", \"description\":\"new-description\"}" "http://localhost:8080/api/tasks/cb06d6a1-960b-47eb-b44b-de0b01303020"

HTTP/1.1 200 
Content-Length: 0
Date: Fri, 29 Jul 2022 09:22:34 GMT

So far, all the tests we executed look pretty much the same as the ones executed in the previous article. However, we know that previously, restarting the service implied losing the data. Let's try this now by rebuilding the full stack again:

docker-compose down
docker-compose up --build -d

curl -i -X GET "http://localhost:8080/api/tasks" 

HTTP/1.1 200 
Content-Type: application/json
Content-Length: 163
Date: Fri, 29 Jul 2022 09:27:25 GMT

[{"identifier":"cb06d6a1-960b-47eb-b44b-de0b01303020","title":"new-title","description":"new-description","createdAt":"2022-07-29T09:20:25.410Z","completed":true}]

As we can see, the data is now persistently stored - we still have the original task we initially created and then updated as part of testing.

Summary

In conclusion, what we've done as part of this tutorial is:

• setup a MongoDB container

• use Docker Compose to manage a multi-container application

• integrate a Java REST API with a MongoDB database

The key point I was trying to show in this article was the fact that all we had to do to switch from an in-memory DB implementation to a proper DB technology was to create a new implementation of the repository interface, configure the connection to the DB inside a new guice module and then change one line in the already existing code so that our business logic will now use the new repository implementation.

We changed the guice binding from:

bind(TaskManagementRepository.class).to(InMemoryTaskManagementRepository.class).in(Singleton.class);

to:

bind(TaskManagementRepository.class).to(MongoDBTaskManagementRepository.class).in(Singleton.class);

We never touched any of the core business logic for our API and this is the beauty of clean architecture - we don't couple our code with the fact that we chose to persist our data in a database rather than in-memory. This is an implementation detail and changing our storage mechanism should not affect the rest of our code.

Having seen many tutorials on how to build REST APIs in Java using various combinations of frameworks and libraries, I decided to build my own API using the software suite that I have the most experience with. In particular, I wanted to use:

• Maven as the build and dependency management tool

• Jersey as the framework that provides an implementation of the JAX-RS specification

• Tomcat as the application server

  • in particular, I wanted to run Tomcat in embedded mode so that I would end up with a simple executable jar file

• Guice as the dependency injection framework

The problem I faced was that I couldn't find any tutorials combining the software choices above, so I had to go through the process of combining the pieces myself. This didn't turn out to be a particularly straightforward task, which is why I decided to document the process on my blog and share it with others who might be facing similar problems.

Project Summary

For this tutorial, we are going to build the standard API for managing TODO items - i.e. a CRUD API that supports the functionalities of Creating, Retrieving, Updating and Deleting tasks.

The API specification is given below:

The full specification can be viewed in the Appendix.

To implement this API, we will use:

• Java 11 (OpenJDK)

• Apache Maven v3.8.6

• Ecplipse Jersey v2.35

• Apache Tomcat v9.0.62

• Guice v4.2.3

For simplicity, I will avoid the use of any databases as part of this tutorial and instead use a pseudo-in-memory DB. However, we will see how easy it is to switch from an in-memory testing DB to an actual database when following a clean architecture.

The goal is to end up with an executable jar file generated by Maven that will include the Tomcat application server and our API implementation. We will then dockerize the entire process of generating the file and executing it, and finally, run the service as a Docker container.

The following coding steps will only outline the most relevant pieces of code for this tutorial, but you can find the full code in the GitHub repository. For most steps, we will add unit tests that won't be referenced here but included in the code change itself. To run the tests at any given point in time, you can use mvn clean test.

Coding Steps

Step 1 - Project Setup

As with every Maven project, we need a POM file (the file representing the Project object Model). We start with a very basic POM which describes the project information and sets the JDK and JRE target versions to 11. This means that the project can use Java 11 language features (but no features from later versions) and will require a JRE version 11 or later to be executed. To avoid registering a domain name for this example project, I am using a group ID that corresponds to my GitHub username where this project will be hosted - com.github.nikist97.

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- Project Information -->
    <groupId>com.github.nikist97</groupId>
    <artifactId>TaskManagementService</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>TaskManagementService</name>

    <properties>
        <!-- Maven-related properties used during the build process -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <dependencies>
        <!--     This is where we will declare libraries our project depends on     -->
    </dependencies>

    <build>
        <plugins>
            <!--     This is where we will declare plugins our project needs for the build process     -->
        </plugins>
    </build>
</project>

The full commit for this step can be found here.

Step 2 - Implementing the Business Logic

We start with the most critical piece of software in general, which is our business logic. Ideally, this layer should be agnostic to the notion of any DB technologies or API protocols. Whether we implement an HTTP API using MongoDB on the backend or we use PostgreSQL and implement a command-line tool for interacting with our code, it should not affect the code for our business logic. In other words, the business logic should not depend on the persistence layer (the code interacting with the database) and the API layer (the code that will define the HTTP API endpoints).

The first thing to implement is our main entity class - Task. This class follows the builder pattern and provides argument validation. The required attributes are the task's title and description. For the rest of the attributes we can default to sensible values when not explicitly provided:

• identifier is set to a random UUID

• createdAt is set to the current datetime

• completed is set to False

public class Task {

    private final String identifier;
    private final String title;
    private final String description;
    private final Instant createdAt;
    private final boolean completed;

    ...

    public static class TaskBuilder {

        ...

        private TaskBuilder(String title, String description) {
            validateArgNotNullOrBlank(title, "title");
            validateArgNotNullOrBlank(description, "description");

            this.title = title;
            this.description = description;
            this.identifier = UUID.randomUUID().toString();
            this.createdAt = Instant.now();
            this.completed = false;
        }

        ...

    }
}

Then, we define the interface we need for interacting with a persistence layer (i.e. a database or another storage mechanism). Notice that this interface belongs to the business layer because, ultimately, it is the business logic that decides what storage functionality we will need. The actual implementation of this interface, though (a MongoDB implementation or an in-memory DB or something else) will belong to the persistence layer, which we will implement in a subsequent step.

public interface TaskManagementRepository {

    void save(Task task);

    List<Task> getAll();

    Optional<Task> get(String taskID);

    void delete(String taskID);
}

Finally, we implement the service class, which has the CRUD logic. The critical piece here is that this class doesn't rely on a concrete implementation of the repository interface - it is agnostic to what DB technology we decide to use later.

public class TaskManagementService {

    private final TaskManagementRepository repository;

    ...

    public Task create(String title, String description)  {
        Task task = Task.builder(title, description).build();

        repository.save(task);

        return task;
    }

    public Task update(String taskID, TaskUpdateRequest taskUpdateRequest) {
        Task oldTask = retrieve(taskID);

        Task newTask = oldTask.update(taskUpdateRequest);
        repository.save(newTask);

        return newTask;
    }

    public List<Task> retrieveAll() {
        return repository.getAll();
    }

    public Task retrieve(String taskID) {
        return repository.get(taskID).orElseThrow(() ->
                new TaskNotFoundException("Task with the given identifier cannot be found - " + taskID));
    }

    public void delete(String taskID) {
        repository.delete(taskID);
    }
}

The way this code was written allows us to easily unit test our business logic in isolation by mocking the behaviuor of the repository interface. To achieve this, we will need to add two dependencies in the POM file:

        ...
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-core</artifactId>
            <version>3.5.13</version>
            <scope>test</scope>
        </dependency>
        ...

The full commit for this step can be found here.

Step 3 - Creating Stub API Endpoints

The next step is to implement the API layer. For this project, we are implementing an HTTP REST API using Jersey. Therefore, we start by adding the dependency in the POM file.

        ...
        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
            <version>2.35</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.inject</groupId>
            <artifactId>jersey-hk2</artifactId>
            <version>2.35</version>
        </dependency>
        ...

The second dependency is needed after Jersey 2.26 - https://eclipse-ee4j.github.io/jersey.github.io/release-notes/2.26.html - following this version users need to explicitly declare the dependency injection framework for Jersey to use - in this case, we go with HK2 which is what was used in previous releases.

Then we implement the resource class, which at this point only has stub methods that all return a status code 200 HTTP response with no response body.

@Path("/tasks")
public class TaskManagementResource {

    @POST
    public Response createTask() {
        return Response.ok().build();
    }

    @GET
    public Response getTasks() {
        return Response.ok().build();
    }

    @PATCH
    @Path("/{taskID}")
    public Response updateTask(@PathParam("taskID") String taskID) {
        return Response.ok().build();
    }

    @GET
    @Path("/{taskID}")
    public Response getTask(@PathParam("taskID") String taskID) {
        return Response.ok().build();
    }

    @DELETE
    @Path("/{taskID}")
    public Response deleteTask(@PathParam("taskID") String taskID) {

        return Response.ok().build();
    }
}

We will also need an application config class to define the base URI for our API and to inform the framework about the task management resource class:

@ApplicationPath("/api")
public class ApplicationConfig extends ResourceConfig {

    public ApplicationConfig() {
        register(TaskManagementResource.class);
    }

}

The full commit for this step can be found here.

Step 4 - Implementing the API Layer

For this project, we will use JSON as the serialization data format for HTTP requests and responses.

To produce and consume JSON in our API, we need to add a library that's going to be responsible for the JSON serialization and deserialization of POJOs. We are going to use Jackson. The library we need to integrate Jersy with Jackson is given below:

        ...
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-json-jackson</artifactId>
            <version>2.35</version>
        </dependency>
        ...

Then we need to customize the behaviour of the JSON object mapper that will be used for serializing and deserializing the request and response POJOs. In this case, we disable ALLOW_COERCION_OF_SCALARS - this means that the service won't attempt to parse strings into numbers or booleans (e.g. {"boolean_field":"true"} will be rejected)

@Provider
public class JsonObjectMapperProvider implements ContextResolver<ObjectMapper> {

    private final ObjectMapper jsonObjectMapper;

    /**
     * Create a custom JSON object mapper provider.
     */
    public JsonObjectMapperProvider() {
        jsonObjectMapper = new ObjectMapper();
        jsonObjectMapper.disable(ALLOW_COERCION_OF_SCALARS);
    }

    @Override
    public ObjectMapper getContext(Class<?> type) {
        return jsonObjectMapper;
    }
}

Once again, we need to make Jersey aware of this provider class:

@ApplicationPath("/api")
public class ApplicationConfig extends ResourceConfig {

    public ApplicationConfig() {
        register(TaskManagementResource.class);
        register(JsonObjectMapperProvider.class);
    }

}

Then we define the request and response POJOs. I will skip the code for these classes, but in summary, we need:

• TaskCreateRequest - represents the JSON request body sent to the service when creating a new task

• TaskUpdateRequest - represents the JSON request body sent to the service when updating an existing task

• TaskResponse - represents the JSON response body sent to the client when retrieving task(s)

The last part of this step is to replace the stub logic in the resource class with the actual API implementation that relies on the business logic encapsulated in the service class from step 2.

@Path("/tasks")
public class TaskManagementResource {

    private final TaskManagementService service;

    public TaskManagementResource(TaskManagementService service) {
        this.service = service;
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response createTask(TaskCreateRequest taskCreateRequest) {
        validateArgNotNull(taskCreateRequest, "task-create-request-body");

        Task task = service.create(taskCreateRequest.getTitle(), taskCreateRequest.getDescription());

        String taskID = task.getIdentifier();

        URI taskRelativeURI = URI.create("tasks/" + taskID);
        return Response.created(taskRelativeURI).build();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<TaskResponse> getTasks() {
        return service.retrieveAll().stream()
                .map(TaskResponse::new)
                .collect(Collectors.toUnmodifiableList());
    }

    @PATCH
    @Path("/{taskID}")
    @Produces(MediaType.APPLICATION_JSON)
    public Response updateTask(@PathParam("taskID") String taskID, TaskUpdateRequest taskUpdateRequest) {
        validateArgNotNull(taskUpdateRequest, "task-update-request-body");

        TaskUpdate update = new TaskUpdate(taskUpdateRequest.getTitle(), taskUpdateRequest.getDescription(),
                taskUpdateRequest.isCompleted());

        service.update(taskID, update);

        return Response.ok().build();
    }

    @GET
    @Path("/{taskID}")
    @Produces(MediaType.APPLICATION_JSON)
    public TaskResponse getTask(@PathParam("taskID") String taskID) {
        Task task = service.retrieve(taskID);
        return new TaskResponse(task);
    }

    @DELETE
    @Path("/{taskID}")
    public Response deleteTask(@PathParam("taskID") String taskID) {
        service.delete(taskID);
        return Response.noContent().build();
    }

The full commit for this step can be found here.

Step 5 - Implementing the Storage Mechanism

For simplicity, we are going to implement an in-memory storage implementation of the repository interface rather than relying on a specific DB technology. The implementation will store all tasks inside a map - the key is the task identifier and the value is the task itself. This is just enough for simple CRUD functionality.

public class InMemoryTaskManagementRepository implements TaskManagementRepository {

    Map<String, Task> tasks = new HashMap<>();

    @Override
    public void save(Task task) {
        tasks.put(task.getIdentifier(), task);
    }

    @Override
    public List<Task> getAll() {
        return tasks.values().stream()
                .collect(Collectors.toUnmodifiableList());
    }

    @Override
    public Optional<Task> get(String taskID) {
        return Optional.ofNullable(tasks.get(taskID));
    }

    @Override
    public void delete(String taskID) {
        tasks.remove(taskID);
    }

}

The full commit for this step can be found here.

Step 6 - Binding Everything Together

Now that we have all the layers implemented, we need to bind them together with a dependency injection framework - in this case, we will use Guice to achieve that.

We start by adding Guice as a dependency in the POM file:

        <dependency>
            <groupId>com.google.inject</groupId>
            <artifactId>guice</artifactId>
            <version>4.2.3</version>
        </dependency>

Then we create a simple Guice module to bind the in-memory DB implementation to the repository interface. This means that for all classes that depend on the repository interface, Guice will inject the in-memory DB class. We use the Singleton scope because we want all classes that depend on the repository to re-use the same in-memory DB instance.

public class ApplicationModule extends AbstractModule {

    @Override
    public void configure() {
        bind(TaskManagementRepository.class).to(InMemoryTaskManagementRepository.class).in(Singleton.class);
    }

}

Note that if we decide to use an actual database, the code change is as simple as:

• implementing the wrapper class for the DB we choose - e.g. MongoDBTaskManagementRepository

• changing the binding above to point to the new implementation of the repository interface

Now that we have the module implemented, we can add Inject annotation to all classes where the constructor has a dependency which needs to be injected by Guice. These would be the TaskManagementResource and the TaskManagementService classes. The magic of Guice (and dependency injection in general) is that the module above is enough to build the entire tree of dependencies in our code.

TaskManagementResource depends on TaskManagementService which depends on TaskManagementRepository. Guice knows how to get an instance of the TaskManagementRepository interface so following this chain it also knows how to get an instance of the TaskManagementService and TaskManagementResource classes.

The final piece of work is to make Jersey aware of the Guice injector - remember Jersey uses HK2 as its dependency injection framework, so Jersey will rely on HK2 to be able to build a TaskManagementResource class. For HK2 to build a TaskManagementResource it needs to know about Guice's dependency injector container. To connect Guice and HK2, we are going to use something called the Guice/HK2 Bridge. It is a process of bridging the Guice container (the Injector class) into the HK2 container (the ServiceLocator class).

So we declare a dependency on the Guice/HK2 bridge library:

        ...
        <dependency>
            <groupId>org.glassfish.hk2</groupId>
            <artifactId>guice-bridge</artifactId>
            <version>2.6.1</version>
        </dependency>
        ...

Then we change the ApplicationConfig class to create the bridge between Guice and HK2. Notice that since the ApplicationConfig class is used by Jersey (and thus managed by HK2) we can easily inject the ServiceLocator instance (the HK2 container itself) into it.

        @Inject
        public ApplicationConfig(ServiceLocator serviceLocator) {
            register(TaskManagementResource.class);
            register(JsonObjectMapperProvider.class);

            // bridge the Guice container (Injector) into the HK2 container (ServiceLocator)
            Injector injector = Guice.createInjector(new ApplicationModule());
            GuiceBridge.getGuiceBridge().initializeGuiceBridge(serviceLocator);
            GuiceIntoHK2Bridge guiceBridge = serviceLocator.getService(GuiceIntoHK2Bridge.class);
            guiceBridge.bridgeGuiceInjector(injector);
        }

The full commit for this step can be found here.

Step 7 - Creating the Application Launcher

The final critical step is configuring and starting the application server through a launcher class, which will serve as our main class for the executable jar file we are targeting.

We start with the code for starting an embedded Tomcat server. The dependency we need is:

    ...
    <dependency>
        <groupId>org.apache.tomcat.embed</groupId>
        <artifactId>tomcat-embed-core</artifactId>
        <version>9.0.62</version>
    </dependency>
    ...

Then we need a launcher class. This class is responsible for starting the embedded Tomcat server and registering a servlet container for the resource config we defined earlier (when we registered the resource class).

public class Launcher {

    public static void main(String[] args) throws Exception {
        Tomcat tomcat = new Tomcat();

        // configure server port number
        tomcat.setPort(8080);

        // remove defaulted JSP configs
        tomcat.setAddDefaultWebXmlToWebapp(false);

        // add the web app
        StandardContext ctx = (StandardContext) tomcat.addWebapp("/", new File(".").getAbsolutePath());
        ResourceConfig resourceConfig = new ResourceConfig(ApplicationConfig.class);
        Tomcat.addServlet(ctx, "jersey-container-servlet", new ServletContainer(resourceConfig));
        ctx.addServletMappingDecoded("/*", "jersey-container-servlet");

        // start the server
        tomcat.start();
        System.out.println("Server listening on " + tomcat.getHost().getName() + ":" + tomcat.getConnector().getPort());
        tomcat.getServer().await();
    }
}

If using IntelliJ to code this project, then you should ideally be able to run the main method of the Launcher class. There is one caveat here - with the release of JDK 9 and after (and hence the introduction of the Java Platform Module System), reflective access is only allowed to publicly exported packages. This means that Guice will fail at runtime because it uses reflection to access JDK modules. See this StackOverflow post for more information.

The only workaround I found so far for this was to add the following as a JVM option --add-opens java.base/java.lang=ALL-UNNAMED to the run configuration of the main method as suggested in the StackOverflow post I linked. This basically allows Guice to continue doing its reflection as in the pre-JDK 9 releases.

After we use the workaround above and test our launcher, we get to the part of generating an executable JAR file which can be used to start the service. To achieve this, we need the appassembler plugin. Note that we still need to add the --add-opens java.base/java.lang=ALL-UNNAMED JVM argument for the executable jar file to work.

         ...
         <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>appassembler-maven-plugin</artifactId>
                <version>2.0.0</version>
                <configuration>
                    <assembleDirectory>target</assembleDirectory>
                    <extraJvmArguments>--add-opens java.base/java.lang=ALL-UNNAMED</extraJvmArguments>
                    <programs>
                        <program>
                            <mainClass>taskmanagement.Launcher</mainClass>
                            <name>taskmanagement_webapp</name>
                        </program>
                    </programs>
                </configuration>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>assemble</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        ...

With this plugin, we can finally generate an executable file and then use it to start the service:

mvn clean package
./target/bin/taskmanagement_webapp

The full commit for this step can be found here.

Step 8 - Adding Exception Mappers

You might have noticed that so far we have defined two custom exceptions that are thrown when the service receives input data it cannot handle:

• TaskNotFoundException

• InvalidTaskDataException

If these exceptions aren't handled properly when encountered, then the embedded tomcat server will wrap them inside an internal server error (status code 500) which is not very user-friendly. As per the API specification we defined in the beginning (see Appendix), we want clients to receive a 404 status code if, for example, they use a task ID that doesn't exist.

To achieve this, we use exception mappers. When we register those mappers, Jersey will use them to transform instances of these exceptions to proper HTTP Response objects.

public class TaskNotFoundExceptionMapper implements ExceptionMapper<TaskNotFoundException> {

    @Override
    public Response toResponse(TaskNotFoundException exception) {
        return Response
                .status(Response.Status.NOT_FOUND)
                .entity(new ExceptionMessage(exception.getMessage()))
                .type(MediaType.APPLICATION_JSON)
                .build();
    }

}

public class InvalidTaskDataExceptionMapper implements ExceptionMapper<InvalidTaskDataException> {

    @Override
    public Response toResponse(InvalidTaskDataException exception) {
        return Response
                .status(Response.Status.BAD_REQUEST)
                .entity(new ExceptionMessage(exception.getMessage()))
                .type(MediaType.APPLICATION_JSON)
                .build();
    }

}

    @Inject
    public ApplicationConfig(ServiceLocator serviceLocator) {
        ...
        register(InvalidTaskDataExceptionMapper.class);
        register(TaskNotFoundExceptionMapper.class);
        ...
    }

Notice the use of a new POJO - ExceptionMessage - which is used to convey the exception message as a JSON response. Now, whenever the business logic throws any of these exceptions, we will get a proper JSON response with the appropriate status code.

The full commit for this step can be found here.

Dockerizing the Application

There are lots of benefits to using Docker but given that this article is not about containers, I won't spend time talking about them. I will only mention that I always prefer to run applications in a Docker container because it makes the build process much more efficient (think application portability, well-defined build behaviour, improved deployment process, etc.)

The Dockerfile for our service is relatively simple and based on the maven OpenJDK image. It automates what we did in step 7 - packaging the application and running the executable jar file.

FROM maven:3.8.5-openjdk-11-slim
WORKDIR /application

COPY . .

RUN mvn clean package

CMD ["./target/bin/taskmanagement_webapp"]

With this, we can build the container image and start our service as a Docker container. The commands below assume you have the Docker daemon running on your local machine.

docker build --tag task-management-service .
docker run -d -p 127.0.0.1:8080:8080 --name test-task-management-service task-management-service

Now the service should be running in the background and be accessible from your local machine on port 8080. For starting/stopping it, use this command:

docker start/stop test-task-management-service

Testing the Service

Now that we have the service running, we can use Curl to send some test requests.

• creating a few tasks

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title\", \"description\":\"description\"}" "http://localhost:8080/api/tasks" 

HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/d2c4ed20-2538-44e5-bf19-150db9f6d83f
Content-Length: 0
Date: Tue, 28 Jun 2022 07:52:46 GMT

curl -i -X POST -H "Content-Type:application/json" -d "{\"title\": \"test-title\", \"description\":\"description\"}" "http://localhost:8080/api/tasks"

HTTP/1.1 201 
Location: http://localhost:8080/api/tasks/64d85db4-905b-4c62-ba10-13fcb19a2546
Content-Length: 0
Date: Tue, 28 Jun 2022 07:52:47 GMT

• retrieving a task

curl -i -X GET "http://localhost:8080/api/tasks/64d85db4-905b-4c62-ba10-13fcb19a2546"

HTTP/1.1 200 
Content-Type: application/json
Content-Length: 162
Date: Tue, 28 Jun 2022 07:54:21 GMT

{"identifier":"64d85db4-905b-4c62-ba10-13fcb19a2546","title":"test-title","description":"description","createdAt":"2022-06-28T07:52:47.872859Z","completed":false}

• retrieving a non-existing task

curl -i -X GET "http://localhost:8080/api/tasks/random-task-id-123"                                                       

HTTP/1.1 404 
Content-Type: application/json
Content-Length: 81
Date: Tue, 28 Jun 2022 09:44:53 GMT

{"message":"Task with the given identifier cannot be found - random-task-id-123"}

• retrieving all tasks

curl -i -X GET "http://localhost:8080/api/tasks"     

HTTP/1.1 200 
Content-Type: application/json
Content-Length: 490
Date: Tue, 28 Jun 2022 07:55:08 GMT

[{"identifier":"64d85db4-905b-4c62-ba10-13fcb19a2546","title":"test-title","description":"description","createdAt":"2022-06-28T07:52:47.872859Z","completed":false},{"identifier":"d2c4ed20-2538-44e5-bf19-150db9f6d83f","title":"test-title","description":"description","createdAt":"2022-06-28T07:52:46.444179Z","completed":false}]

• deleting a task

curl -i -X DELETE "http://localhost:8080/api/tasks/64d85db4-905b-4c62-ba10-13fcb19a2546"

HTTP/1.1 204 
Date: Tue, 28 Jun 2022 07:56:55 GMT

• patching a task

curl -i -X PATCH -H "Content-Type:application/json" -d "{\"completed\": true, \"title\": \"new-title\", \"description\":\"new-description\"}" "http://localhost:8080/api/tasks/d2c4ed20-2538-44e5-bf19-150db9f6d83f"

HTTP/1.1 200 
Content-Length: 0
Date: Tue, 28 Jun 2022 08:00:37 GMT

curl -i -X GET "http://localhost:8080/api/tasks/d2c4ed20-2538-44e5-bf19-150db9f6d83f"   
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 164
Date: Tue, 28 Jun 2022 08:01:07 GMT

{"identifier":"d2c4ed20-2538-44e5-bf19-150db9f6d83f","title":"new-title","description":"new-description","createdAt":"2022-06-28T07:52:46.444179Z","completed":true}

• patching a task with empty title

curl -i -X PATCH -H "Content-Type:application/json" -d "{\"title\": \"\"}" "http://localhost:8080/api/tasks/d2c4ed20-2538-44e5-bf19-150db9f6d83f"

HTTP/1.1 400 
Content-Type: application/json
Content-Length: 43
Date: Tue, 28 Jun 2022 09:47:09 GMT
Connection: close

{"message":"title cannot be null or blank"}

Future Improvements

What we have built so far is not a production-ready API, but it demonstrates how to get started with the software suite I mentioned at the beginning of this article when building a REST API. Here are some future improvements that can be made:

• using a database for persistent storage

• adding user authentication and authorization - tasks should be scoped per user rather than being available globally

• adding logging

• adding KPI (Key Performance Indicators) metrics - things like the count of total requests, latency, failures count, etc.

• adding a mapper for unexpected exceptions - we don't want to expose a stack trace if the service encounters an unexpected null pointer exception, instead we want a JSON response with status code 500

• adding automated integration tests

• adding a more verbose response to the patch endpoint - e.g. indicating whether the request resulted in a change or not

• scanning packages and automatically registering provider and resource classes instead of manually registering them one-by-one

• adding CORS (Cross-Origin-Resource-Sharing) support if we intend to call the API from a browser application hosted under a different domain

• adding SSL support

• adding rate limiting

If you found this article helpful and would like to see a follow-up on the topics above, please comment or message me with a prefered choice of what you would like to learn about the most.

Appendix

The full API specification using the Open API description format can be found below. You can use the Swagger Editor to display the API specification in a more friendly manner.

swagger: '2.0'

info:
  description: This is a RESTful task management API specification.
  version: 1.0.0
  title: Task Management API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

host: 'localhost:8080'
basePath: /api

schemes:
  - http

paths:

  /tasks:
    post:
      summary: Create a new task
      operationId: createTask
      consumes:
        - application/json
      parameters:
        - in: body
          name: taskCreateRequest
          description: new task object that needs to be added to the list of tasks
          required: true
          schema:
            $ref: '#/definitions/TaskCreateRequest'
      responses:
        '201':
          description: successfully created new task
        '400':
          description: task create request failed validation
    get:
      summary: Retrieve all existing tasks
      operationId: retrieveTasks
      produces:
        - application/json
      responses:
        '200':
          description: successfully retrieved all tasks
          schema:
            type: array
            items:
              $ref: '#/definitions/TaskResponse'

  '/tasks/{taskID}':
    get:
      summary: Retrieve task
      operationId: retrieveTask
      produces:
        - application/json
      parameters:
        - name: taskID
          in: path
          description: task identifier
          required: true
          type: string
      responses:
        '200':
          description: successfully retrieved task
          schema:
            $ref: '#/definitions/TaskResponse'
        '404':
          description: task not found
    patch:
      summary: Update task
      operationId: updateTask
      consumes:
        - application/json
      parameters:
        - name: taskID
          in: path
          description: task identifier
          required: true
          type: string
        - name: taskUpdateRequest
          in: body
          description: task update request
          required: true
          schema:
            $ref: '#/definitions/TaskUpdateRequest'
      responses:
        '200':
          description: successfully updated task
        '400':
          description: task update request failed validation
        '404':
          description: task not found
    delete:
      summary: Delete task
      operationId: deleteTask
      parameters:
        - name: taskID
          in: path
          description: task identifier
          required: true
          type: string
      responses:
        '204':
          description: >-
            successfully deleted task or task with the given identifier did not
            exist

definitions:
  TaskCreateRequest:
    type: object
    required:
      - title
      - description
    properties:
      title:
        type: string
      description:
        type: string
  TaskUpdateRequest:
    type: object
    properties:
      title:
        type: string
      description:
        type: string
      completed:
        type: boolean
  TaskResponse:
    type: object
    required:
      - identifier
      - title
      - description
      - completed
      - createdAt
    properties:
      identifier:
        type: string
      title:
        type: string
      description:
        type: string
      createdAt:
        type: string
        format: date-time
      completed:
        type: boolean

SSH is a network protocol allowing two machines (physical or virtual) to establish an encrypted connection and comminucate with each other over an unsecure network without compromising the confidentiality and integrity of the exchanged messages. The protocol uses public-key (a.k.a. asymmetric) cryptography to authenticate an SSH client that wants to connect to an SSH server.

OpenSSH is an implementation of the SSH protocol. All the usage examples given in the next sections are based on it.

SSH Basic Usage

A very common usage of SSH is to login to a remote server. Assuming you have a private/public key pair on your local machine and the public key is also distributed on the server you are trying to login to, then connecting is as simple as running:

ssh <server domain name>
------------------------------
ssh myserver.com

This assumes two things:

• you have an SSH agent running with the appropriate private key added or the path to the private key follows a standard naming convention (e.g. ~/.ssh/id_rsa) - you might need to run ssh-add <path to private key> if this is not the case
  • ~/.ssh/id_rsa is one of the standard naming conventions that the SSH client automatically attempts to use when authenticating with a server
• you want to authenticate with the username on your local machine
  • this assumption will not hold if on my laptop I use something like nikolay as the username but on a server running Ubuntu only the ubuntu user exists

The following command can be used to change the username to authenticate with:

ssh <username>@<server domain name>
---------------------------------------------
ssh ubuntu@myserver.com

Advanced SSH Usage - Tunneling

A more advanced usage of SSH is the so called SSH tunneling (a.k.a. SSH port forwarding). SSH tunneling is a process of establishing communication between a client (in this case, your local machine) and a server (a remote machine) through a jump server (the machine running an SSH server). This is achieved by mapping ports between the client and the SSH server (hence the name "port forwarding").

This can be visualized with the following diagram:

Keep in mind that the remote machine might be the jump server itself.

There are 3 types of port forwarding, the behavior of which will be illustrated in the following sections. All the example commands assume that the client's public key is already distributed to the SSH server and that the client can successfully login to the SSH server using the command given in the previous section.

N.B. remember that if using a different username on your local machine and on the SSH server, then you need to include <SSH server username>@ in front of all the "jump server" references for the examples below to work - for example, instead of mysshserver.com you might have to use something like user@mysshserver.com

Local Port Forwarding

Local port forwarding is the process of tunneling connections initiated by the client machine through a jump server and forwarding these connections to a remote server or the jump server itself.

To initiate this, run the command below on your local machine:

ssh -N -f -L <local port>:<target server domain name>:<remote port> <jump server domain name>
------------------------------------------------------------------------------------------------------
ssh -N -f -L 5001:mytargetapp.com:5002  mysshserver.com

With the example above, all connections to port 5001 on your local machine will be tunneled (in an encrypted manner) to the SSH jump server (mysshserver.com) and then forwarded to mytargetapp.com at port 5002.

The CLI flags are explained below:

• -L - this is the key flag that instructs the SSH client to execute local port forwarding
• -N - by default the SSH client will open a session even when executing local port forwarding; this flag instructs the client to not execute a remote command (i.e. only forward ports)
• -f - this instructs the ssh client to run in the background (so that you don't need to keep your terminal open while port forwarding is running)

Another example where we are not forwarding to a remote machine but to the jump server itself:

ssh -N -f -L 5001:localhost:5002  mysshserver.com

With this, any connections to port 5001 on your local machine are tunneled to port 5002 on the jump server itself (mysshserver.com).

Remote Port Forwarding

Remote port forwarding is the reverse process of local port forwarding - forwarding connections initiated by a remote machine (or the jump server itself) through the jump server and tunneling these connections back to your local machine on the specified target port.

To initiate this, run the command below on your local machine:

ssh -N -f -R <remote port>:localhost:<local port> <jump server domain name>
------------------------------------------------------------------------------------------------------
ssh -N -f -R 5001:localhost:5002  mysshserver.com

The example above shows a scenario where port 5001 will be open for connections on the jump server (mysshserver.com), any connection to it will be tunneled back to your local machine (in an encrypted manner), and then forwarded to the application listening on the target port - 5002.

The only new CLI flag in this case is -R which instructs the SSH client to execute remote port forwarding. Remote port forwarding is a very common solution if you want to temporarily expose an application running on your local machine to the public (assuming the SSH server is publicly available on the internet) or to someone that has network access to the SSH server in general (for example, through a VPN).

Dynamic Port Forwarding

Dynamic port forwarding is similar to local port forwarding in the sense that local connections are tunneled (in an encrypted manner) to the SSH jump server. The difference is that with dynamic port forwarding you don't need to specify a target host or port - all connections are forwarded to the original target host and target port through the SSH server. In technical terms, dynamic port forwarding is the process of using the SSH server as a SOCKS5 proxy server.

To initiate this run:

ssh -N -f -D <local proxy port> <jump server domain name>
------------------------------------------------------------------------------------------------------
ssh -N -f -D 1080 mysshserver.com

The new CLI flag in this case is -D which instructs the SSH client to execute dynamic port forwarding. The recommendation is to use port 1080 as it is the standard SOCKS protocol port number.

Then you can configure your browser (say Firefox - see this tutorial) or any other application that supports SOCKS/SOCKS5 proxies to use this tunnel and securely forward your network traffic through the SSH jump server (mysshserver.com). In essense, this gives you a very basic VPN functionality by hiding data about your local machine - websites you visit will see traffic that seems to be coming from the SSH server.

The diagram above illustrates an example where the client is accessing somewebsite.com through dynamic port forwarding. The browser uses the proxy to connect to the website. The communciation between the local machine and the SSH server (mysshserver.com) is encrypted. The SSH server then forwards the request to the actual website. From the perspective of somewebsite.com the conenction was initiated from the SSH server rather than the local machine.

Nginx is by far one of the most famous and most commonly deployed web servers out in the world - check the web servers' usage statistics provided by W3Techs. Nginx can also act as a proxy server, load balancer, caching server, etc. - feel free to read the official docs for more information on what the product can offer you.

My first experience with Nginx was when trying to use it as an API gateway (more like a single entry point for a system) proxying requests to multiple back-end services. I fell in love with the simplicity of a product with so many capabilities. Since then, I've used it for multiple projects and would still prefer it in comparison to alternative web servers.

I decided to write this post to illustrate some of the features I found super useful during my experience with Nginx which in my opinion turned out to be incredibly simple to configure. In no particular order, the list is given in the next section.

If you don't understand the http/server/location directives in the configuration examples below or you haven't seen any Nginx configuration before, please refer to this guide for more details.

How-tos

Limit request body size

Very often when developing an API we let users upload arbitrary files - be they image files, video files, archives, etc. This would commonly imply sending a large amount of bytes as part of the HTTP request body. When left with no validation this functionality can lead to unexpected storage costs or even memory exhaustion if the backend server loads the whole file into memory. Nginx can easily provide protection for this by enforcing a limit on the size of the request body. Here is an example configuration.

http {
    ...
    client_max_body_size 500M;
    ... 
}

Yes, it is that simple. This line is enough to ensure the body of all HTTP requests sent to this host does not exceed 500 megabytes. Any requests that exceed the limit will receive a client error response with status code 413 (Request Entity Too Large).

Another example is given below - enforcing the limit for a particular URI pattern rather than for every single request:

http {
    ...
    server {
        ...
        listen 80;

        location /api/pictures {
            ...
            client_max_body_size 500M;
            ...
        }
        ...
    }
    ...
}

The config above defines an HTTP server listening on port 80 and enforces all requests sent to URIs starting with /api/pictures to have a maximum body size of 500 megabytes. For more details on this, please see the official docs

N.B. the default threshold is 1 megabyte

Add HTTP basic authentication

A common use case website developers have is restricting access to certain sub-pages of their website. Personally, what I also commonly do during manual testing of a new website/API is restrict access to the entire application to a particular set of test users until the release is official. Nginx's auth basic module can easily allow us to do just that. For example:

http {
    ...
    auth_basic "Please authenticate";
    auth_basic_user_file /etc/nginx/.htpasswd;
    ... 
}

This config restricts the entire Nginx server using HTTP Basic Authentication. Keep in mind the /etc/nginx/.htpasswd file must contain the list of <username>:<password> pairs and is expected to follow a certain format. Please see this tutorial for how to generate the necessary password file.

The same configuration can be used to only restrict a particular URI pattern:

http {
    ...
    server {
        ...
        listen 80;

        location /admin {
            ...
            auth_basic "Please authenticate";
            auth_basic_user_file /etc/nginx/.htpasswd;
            ...
        }
        ...
    }
    ...
}

Limit API access to read-only requests

Sometimes when exposing a local back-end service to the public through Nginx (acting as a proxy) I only want to allow read-only (e.g. GET and HEAD) requests that the front-end needs for retrieving content - for example, I might not want to expose publicly any ops-related DELETE API endpoints. Nginx supports this through the limit_except directive:

http {
    ...
    server {
        ...
        listen 80;

        location /api {
            ...
            limit_except GET {
                deny  all;
            }
            ...
        }
        ...
    }
    ...
}

N.B. the HEAD method is automatically included when allowing the GET method

Add SSL support

Who doesn't love the message from our browsers indicating that the connection with a particular website is secure? To enable this for an Nginx web server we can use the Nginx SSL module:

http {
    ...
    server {
        ...
        listen 443 ssl;

        ssl_certificate <path to certificate file in PEM format>;
        ssl_certificate_key <path to private/secret key file in PEM format>;
        ...
    }
    ...
}

This config assumes you know how to generate an SSL certificate. One of the simplest ways to do this is to use Let's encrypt - follow this tutorial. Ultimately, you should end up with fullchain.pem and privkey.pem; these are the files you need for the ssl_certiciate and ssl_certificate_key directives respectively.

Rate limiting clients

Rate limiting is the process of ensuring that an individual client cannot exceed a given threshold of requests for a given unit of time - e.g. ensuring that each client can send a maximum of 5 requests per second. The module for configuring this is the Nginx HTTP Limit Request Module.

http {
    ...
    limit_req_zone $binary_remote_addr zone=books:10m rate=5r/s;
    ...
    server {
        ...
        listen 80;

        location /api/books {
            ...
            limit_req zone=books;
            ...
        }
        ...
    }
    ...
}

Here we need one directive (limit_req_zone) for defining the rate limiting "zone" (a re-usable rate limiting configuration) and another directive (limit_req) for indicating that we want to enable the rate limiting zone for a particular context (e.g. a URI location pattern). The limit_req directive can also be used inside a server or http context - in other words, rate limiting can be applied for all virtual servers, for an individual virtual server or for a particular URI location pattern.

By default, clients that exceed the rate limiting threshold will receive a status code 503 Service Unavailable. This is also configurable with the limit_req_status directive:

http {
    ...
    limit_req_zone $binary_remote_addr zone=books:10m rate=5r/s;
    ...
    server {
        ...
        listen 80;

        location /api/books {
            ...
            limit_req zone=books;
            limit_req_status 429;
            ...
        }
        ...
    }
    ...
}

Redirect HTTP traffic to HTTPs

A very very very common scenario for web servers is to automatically redirect all clients who connect to the non-encrypted version of a website (HTTP traffic - i.e. server listening on port 80) to the safer encrypted version of the website (HTTPs traffic - i.e. server listening on port 443). Redirection is another easy thing to configure in Nginx:

http {
    ...
    server {
        listen 80;
        return 301 https://$host$request_uri;
    }
    server {
        ...
        listen 443;
        ...
    }
    ...
}

What this config means is that Nginx will return a status code 301 (Moved Permanently) to all clients that connect to port 80. The redirection target will be a URL that uses the same host name and request URI but with https rather than http as the URL scheme. Browsers will automatically follow the redirection and move clients to the secure version of our website.