We'll also deploy the application on Azure App Service and make it production-ready by setting up features like autoscaling and multiple environments.

You'll learn how Neon Postgres can make your development and deployment processes easier along the way.

Here's what we'll cover:

• Setting up a Neon Postgres database and exploring its features
• Building a CRUD application using Spring Boot and deploying the application on Azure App Service
• Why Neon is a good fit for infrastructure that auto-scales
• Database branching in Neon Postgres and how it can ease the development workflow

Prerequisites

• Working knowledge of Java, Maven, and Spring Boot
• Basics of SQL databases
• Understanding of serverless and cloud services
• Familiarity with testing and deployment processes

Table of Contents

• What is Neon Postgres?
• How to Set Up the Database
  • Create the Database
• How to Build the Spring Boot CRUD App
  • Create an Entity Class
  • Create a Repository
  • Create a REST Controller
  • Configure the Database
• How to Deploy on Azure App Service
  • Create a New Web App
  • Deploy the Application
  • Access the Application
• How to Set Up Autoscaling
  • Autoscaling in Azure
  • Autoscaling in Neon
• How to Configure Database Branches in Neon
• Summary

What is Neon Postgres?

Neon is a fully managed serverless Postgres database platform. It offers features such as high availability, automatic backups, and scaling options to handle varying traffic levels.

Neon is designed to be cost-efficient and developer-friendly, and it focuses on providing a seamless experience for developers.

In addition to the standard Postgres features, it provides capabilities like database branching, allowing you to create Git-like branches of the database for different purposes.

How to Set Up the Database

To begin with, let's explore how you can set up a Neon database for your application.

Firstly, you'll need to create an account on the Neon website. It doesn't require a credit card to sign up, and you're automatically set up with the free tier to get started.

Here's a pricing and features comparison of Neon plans:

Neon pricing plans

In the free tier, we get 0.5 GB of storage with basic computing which is enough for playing around with the database and building small applications.

Create the Database

Once you've signed up, you can access the dashboard and create a new project.

Star by filling in the project name, region, and Postgres version options. In addition to this, we can choose two additional options:

• compute size – You can choose a min and max compute size for the database. This is useful for autoscaling the database based on the load.
• suspend time – You can set a time after which the database will be suspended if not being used. This is useful for saving costs when the database is not being used.

Creating a database project in Neon

Once you submit the form, Neon will create the database and provide the connection details.

Neon Dashboard

As you can see, the database was set up in 3.3 seconds (compared to hours of installing and setting up your own infrastructure). You can choose multiple ways to connect to the database. For this tutorial, select Java as your programming language and get the JDBC connection string.

How to Build the Spring Boot CRUD App

Next, let's set up our CRUD application. We'll use Spring Boot, as it provides easy bootstrapping and configuration for building web applications.

We can use the Spring Initializr to generate a new Spring Boot project with the necessary dependencies:

• Spring Web – for building web applications
• Spring Data JPA – for working with databases using JPA
• PostGres Driver – for connecting to the Postgres database

Creating a Spring Boot project using Spring Initializer

You can generate, download, and import the project into your favorite IDE.

Create an Entity Class

Let's create an entity class to represent the data in the application. First, create a User class:

@Entity(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // Constructors, Getters and Setters
}

The entity name users is the name of the table you want to use in your database.

Create a Repository

Next, create a repository interface to interact with the database. You'll extend the JpaRepository interface provided by Spring Data JPA:

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

You need to annotate the interface with @Repository to mark it as a Spring bean. The JpaRepository interface provides methods for CRUD operations like save, findAll, findById, delete, and so on, so you don't need to write the queries manually.

You'll provide your entity class User and the type of the primary key Long as type arguments to the JpaRepository interface.

Create a REST Controller

Finally, create a REST controller to handle the CRUD operations. You'll inject the UserRepository into the controller and implement the necessary endpoints:

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping
    public List<User> getUsers() {
        return userRepository.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userRepository.save(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userRepository.save(user);
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
    }
}

Here are a few things to note:

• You're using the @RestController annotation to mark the class as a controller that handles REST requests.
• The @RequestMapping annotation specifies the base URL for the endpoints.
• You're injecting the UserRepository into the controller using constructor injection.
• Finally, you're implementing your API endpoints for CRUD operations using the @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping annotations.

Configure the Database

To connect your Spring Boot application to the Neon Postgres database, you need to configure the database URL, username, and password in the application.properties file:

spring.datasource.url=jdbc:postgresql://<db-url>/<db-name>?sslmode=require
spring.datasource.username=<username>
spring.datasource.password=<password>
spring.jpa.hibernate.ddl-auto=update

Here, you configured the database URL, username, and password provided by Neon when you created the database. The spring.jpa.hibernate.ddl-auto=update property tells Spring Boot to automatically create the necessary tables or columns based on the entity classes when the application starts.

How to Deploy on Azure App Service

Now that your Spring Boot application is ready, it's time to deploy it on Azure App Service.

Create a New Web App

To deploy your Spring Boot application on Azure App Service, you'll first create a new Web App. You can do this through the Azure portal by following these steps:

• Log in to the Azure portal.
• Click on the Create a resource button.
• Search for Web App and select the Create option.
• Fill in the necessary details like resource group, app name, runtime stack, and region.
• Click the Review + create button.

Creating a Web App in Azure

Deploy the Application

The Web App takes a couple of minutes to create. Once done, you can deploy your Spring Boot application to Azure App Service.

One of the easiest ways to deploy is to package your Spring Boot application as a JAR file and deploy it to Azure App Service using the Azure CLI.

To do this, run the below commands:

mvn package
az webapp deploy --src-path neon-demo-0.0.1-SNAPSHOT.jar --resource-group learn-ba1a439c-71ca-4cab-9bb1-f5b1331bab04 --name neon-app

Here, you're packaging your Spring Boot application using Maven and deploying the JAR file to Azure App Service using the Azure CLI. You've provided the path to the JAR file, the resource group, and the app name you previously configured.

Access the Application

Once the deployment is complete, you can access your Spring Boot application on Azure App Service by navigating to the URL of the Web App. Your app is available at neon-app.azurewebsites.net

Let's use _curl _to test the endpoints.

Create a User

curl -X POST -d '{"name":"John Doe","email":"john@gmail.com"}' https://neon-app.azurewebsites.net/users

Here you provide user data in JSON format to create a new user.

Get Users

You can also can test that the user was created by fetching all users:

curl -X GET https://neon-app.azurewebsites.net/users

How to Set Up Autoscaling

A production application may experience varying levels of traffic, and it's important to scale the application dynamically based on the load.

Let's explore how you can autoscale your application when needed.

Autoscaling in Azure

Azure App Service provides autoscaling options that let you automatically adjust the number of instances as needed.

You can configure autoscaling rules in the Azure portal by following these steps:

• Navigate to the Web App in the Azure portal.
• Click the Scale out (App Service Plan) option from the left menu.
• Configure the autoscaling rules – you can choose predefined rules like traffic or create custom rules based on metrics like CPU usage, memory usage, or custom metrics.
• Save.

Azure will automatically scale the application based on the configured rules.

Autoscaling in Neon

Since your application is automatically scaled based on the load, you'll want to ensure that the database can handle the increased traffic.

Neon provides autoscaling options to scale the database dynamically based on the load. You can configure autoscaling rules in the Neon dashboard to ensure the database can handle the increased load.

Follow the below steps to configure autoscaling in Neon:

1. Navigate to the Neon dashboard and select the database. Then select the branch to configure autoscaling.

Selecting a branch from Neon project dashboard

2. Click on the Edit button next to the Compute section. Configure the autoscaling rules based on metrics like CPU usage, memory usage, or custom metrics.

Branch details view in Neon

3. Configure the min-max compute size and Save. Neon will automatically scale the database based on the configured rules when needed.

Setting up autoscaling for compute

Ensuring that both the application and the database can scale dynamically based on the load will help you handle varying levels of traffic efficiently.

How to Configure Database Branches in Neon

In a typical development workflow, multiple databases may be used for different purposes like development, testing, and production.

Neon Postgres provides database branching to create multiple branches for different purposes. Each branch is an instance of the database that you can use independently.

This Git-like feature helps set up a copy of the database for different environments like development, staging, and production. It also helps preserve data for different versions of the application.

Let's explore how you can create and manage branches in Neon Postgres:

• Navigate to the Neon dashboard and select the database.
• In the Branches section, click on the View All button.
• You can create a new branch from an existing one by clicking on the Create Branch button. You'll need to provide the branch name and what data to copy from the parent branch.

Create branch option

• You can either copy all the data or copy until a point in time or a specific record. This is useful for multiple purposes like restoring data, creating a new environment, or testing new features.

Creating a new branch

• Neon will create a new branch of the database that can be used independently. You can find the URL, username, and password for the new branch in the dashboard. And this happens in real time without any downtime and delays.

Branch-specific connection details

Now you can use your dev branch for local development and testing, and the main branch for production. This helps in keeping the data separate and ensures that changes in one branch do not affect the other branches.

Summary

In this article, we built a CRUD application using Spring Boot, Neon Postgres, and Azure App Service.

We explored how to set up the Neon Postgres database, build a basic CRUD application using Spring Boot, deploy the application on Azure App Service, and configure autoscaling for the application and the database.

We also learned about how the database branching feature in Neon Postgres helps you create branches of the database for different environments and purposes.

We will cover resource management concepts, data model, APIs, and configuration options.

1. What is Azure Cosmos DB?

Azure Cosmos DB is a document database service that enables us to store, query, and index our data in a highly available, globally consistent, and scalable cloud-based NoSQL database.

It is fully managed which means availability, reliability, and security are all handled for us.

Cosmos DB APIs

The standout feature of Cosmos DB is that you can configure it to use either SQL or NoSQL to interact with your data. It does so by providing different APIs for each type of data you want to store.

The APIs are:

1. SQL API – for storing and querying data using an SQL-like syntax. This is the default and recommended API.
2. Gremlin API – if we want to interact with data using a graph database-like syntax.
3. Table API – for applications migrating from Azure Table Storage to Cosmos DB.
4. Cassandra API – for working with data designed for the Cassandra database.
5. MongoDB API – for working with data designed for the MongoDB database.

By providing these APIs, Cosmos DB makes it easy for us to migrate from an existing data store to Cosmos DB. More on this when we explore how to connect to Cosmos DB programmatically.

Note that the APIs do not determine how the data is stored. The data is stored in a NoSQL database.

Why Choose Cosmos DB?

Since there are other cloud-based databases which you can use to store data, it is important to understand why you might want to migrate to Cosmos DB.

Cosmos DB provides some premium capabilities that may not be available in other cloud-based databases:

• Easy global distribution of data – which increases availability and speed with multi-region write and read operations.
• Dedicated throughput
• Single digit millisecond latency.
• Guaranteed availability
• Advanced indexing and partitioning

and more.

In addition to this, the APIs make it easier to switch between different database approaches without physically migrating data.

2. Basic Azure Cosmos DB Concepts

Let's look at some basic concepts of Azure Cosmos DB.

Resource Hierarchy

Below is the resource hierarchy of Azure Cosmos DB.

Cosmos DB resource Hierarchy

Let's understand each level and the configurations available at the different levels of the hierarchy.

Cosmos Account

A Cosmos Account is the top level resource in Azure Cosmos DB. It is the entry point to our Cosmos DB instances.

The following features are defined at the Cosmos Account level:

1. A unique DNS name used to connect with database instances like https://{account}.documents.azure.com/
2. Global distribution capabilities – you can define how many regions you want to distribute your data across.
3. The default consistency level for all resources in the account. You can override this for individual resources.

Databases and Containers

An account can contain multiple databases which have the same distribution needs. Each database can contain multiple containers. You can also use databases to manage users, permissions, and throughput for underlying containers.

Each container is analogous to a table in SQL, collection in MongoDB, graph in Gremlin, and so on. Containers are fundamental units of scalability for storage and throughput. They are horizontally partitioned and replicated across multiple regions as defined by the account.

The throughput of a container can be defined in two ways:

1. Dedicated provisioned throughput mode – Each container instance can be assigned a fixed throughput. Costlier and backed by SLAs.
2. Shared provisioned throughput mode – The total throughput of all container instances running in shared mode remains the same while individual containers can have different real-time throughputs.

At the container level, we also have the option to configure the indexing policy and default TTL.

Contents of a Container

Similar to an SQL table, a container can contain multiple resources. The most important resource is the Item(s).

An item is a single unit of record. For example, a row in a table, a document in a collection, a node in a graph, and so on.

Some other resources include JavaScript based:

1. Stored procedures
2. User-defined functions
3. Triggers

Consistency levels

Data can be replicated across multiple regions and writes can be allowed. In such scenarios, determining the consistency requirements of the data is important.

Let's look at the different consistency levels available in Azure Cosmos DB and what they mean:

1. Strong – Data remains exactly the same across all regions. This means that the write operation is expensive and does not complete until all regions have the data.
2. Bounded Staleness – The delay in the write operation is bounded by a fixed time interval between the regions. For example, after a write operation is performed, the data is guaranteed to be available in the next t seconds.
3. Session – Data written in a session will be available to read when a read is performed in the same session. This is good when for a user session, all reads and writes are taken care of by a single region.
4. Consistent Prefix – Data will be read in the same sequence in which it is written. For example, if in region 1 we write data A and then B, then in region 2, A will be available before B.
5. Eventual – Both order and staleness do not matter, the only thing important is that data will be eventually available in all regions. Works fast but has the least consistency.

Explore – Scenarios that require different consistency levels.

Request Units (RUs)

According to the definition on Microsoft Learn:

The cost to do a point read, which is fetching a single item by its ID and partition key value, for a 1KB item is 1RU.

The cost is based on system resources such as CPU, IOPS, and memory that are required to perform the database operations. RUs consumed by our application are eventually billed to the account. There are different modes in which the Cosmos account can be set up which will affect billing:

1. Provisioned throughput mode – Set up the expected throughput in terms of RUs per second. The mode is chosen at the account level but the RUs can be provisioned at the database or container level.
2. Serverless mode – Pay for actual consumed units.
3. Autoscale mode – The account is set up to scale automatically based on the usage. This is good for applications with variable or unpredictable usage.

Database Partitioning

As mentioned earlier in the container section, a container can be partitioned into multiple partitions. You do this by setting the partition key.

Partitions and Indexes

• Logical Partitions

A logical partition is a collection of items that share the same partition key value. For example, if a container called "Users" is partitioned by a key "State", then a logical partition is a collection of items that share the same "State" value.

• Index

Indexes are used to improve the performance of queries. In a regular SQL database, an index is created by default based on a primary key. Cosmos DB items also contain a unique field called Item ID.

The default index in Cosmos DB is a combination of the partition key and the item ID. Partition key is used to locate the logical partition and the item ID is used to locate the specific item. Thus, for faster access, it is important to choose a good partition key which distributes the data evenly across the partitions.

• Physical Partitions

The role of physical partitions is to provide horizontal scalability. A physical partition is a collection of one or more logical partitions. Data from a single logical partition cannot exist across more than one physical partition.

The user does not have any control over how the data is distributed across the physical partitions. Cosmos DB is a managed service and the system will automatically distribute the data across the physical partitions when scalability is needed.

This forms the basis of another guideline that partitioning keys should lead to smaller logical partitions. If logical partitions are too large, it will affect the limit to which the system can scale.

How to Choose a Partition Key

By now, we know what a partition key is. But how do we choose a good partition key? Here are a few guidelines:

1. Immutable – The partition key cannot be changed after the data is created.
2. High Cardinality – A large number of possible values for the partition key will lead to a large number of small logical partitions. Good for indexing and scalability.
3. Even Distribution – Apart from high cardinality, it is also important that each possible value is equally likely. This is good for even distribution of data across the partitions.
4. Read heavy containers – For read heavy containers, it's important to choose a partition key that appears frequently in the read queries. Otherwise, the benefit of partition key based index will be lost. It is also beneficial that most queries can read data from a single partition and cross-partition queries are minimized.
5. Using Item ID as a Partition Key – Cosmos DB supports a unique field called Item ID. This field is automatically generated and is guaranteed to be unique. This is a good choice for partition keys.

Explore – Why not use Item ID as a partition key?

Here's some more info on choosing a partition key.

Synthetic Partition Keys

• Concatenate multiple fields together to create a partition key.
• Use a hash function to create a partition key suffix.
• Use a random string to create a partition key suffix.

3. Cosmos DB Data Model

As mentioned earlier, all data in CosmosDB is store in a NoSQL way. Let's look at some aspects of the data model.

Document Data Model

In a document data model, each entry is called a document. In Cosmos DB terminology, documents can be referred to as items.

A document-oriented database will have the below characteristics:

• Non-relational – Each item is an individual entity.
• Easy to scale out – It is possible to create physical partitions for the data to improve performance and to scale storage.
• No schema – The database in itself won't enforce any schema. This gives the flexibility to store entities of different data formats. It also helps the structure evolve over time.

Items

Each item in Cosmos DB is a JSON document. Write operations on these documents are atomic. Items contain a unique Item ID and a partition key which is used to partition the data across multiple logical partitions.

Partition keys can also be nested fields. For example, in the below JSON, city field can be used as a partition key even if it is not at the root level.

{
    "id": "1",
    "name": "John",
    "address": {
        "street": "1 Main St",
        "city": "New York"
    }
}

While creating containers, it is mandatory to provide the partition key path. In the above example, the path will be /address/city.

4. How to Configure Cosmos DB

In Cosmos DB, the SQL API is a query language that allows us to query data in a document database using SQL-like syntax. There are many reasons to choose the SQL API over other APIs:

• Low latency
• Automatic scaling
• 99.999% availability backed by SLAs

It is well suited for high-performance applications like:

• Collecting and querying data from IoT devices – which generates a lot of data and needs to be processed quickly.
• Retail applications – which have varied usage patterns and can benefit from elastic scaling.
• Multi-platform applications – which can benefit from flexibility in document structure.

Throughput Provisioning

When configuring Azure Cosmos DB, we can provision throughput at either or both the database and container levels.

Container Level Throughput

A throughput provisioned at container level applies only to the container. It does not impact other containers of the database. For example, in the below image, each container has a different throughput.

Container-level throughput provisioning

This is the recommended way to provision throughput. If each container is mapped to a separate application function, then it makes sense to provision throughput at container level.

Database Level Throughput

We can also provision throughput at the database level. This will be shared across all containers in the database.

Database Level Throughput Provisioning

This is fine if all containers are expected to have similar load patterns but in most cases, it'll lead to unpredictable results.

Mixed Throughput

It is possible to mix container and database level throughput provisioning. To do so, we first define a throughput at the database level. Then, while creating a container, we can specify which throughput mode to use.

Containers configured in shared throughput mode will share the throughput provisioned at the database level. Containers configured in dedicated throughput mode will have their own throughput provisioned at the container level.

Mixed throughput provisioning

Note that we cannot convert a container from shared to dedicated throughput mode or vice versa. To change this, we need to delete the container and create a new one.

Storage

To estimate storage requirements, we can use the Azure Cosmos DB Capacity Calculator.

Cosmos DB Capacity Calculator

After entering the estimated load, replication strategy, and storage requirements, the calculator can provide an estimated cost of such a setup.

Time to Live (TTL)

It is possible to set a time-to-live (TTL) on documents in a container. This is useful for documents that are expected to be deleted in a short period of time. It can be configured at the container level and can be overridden at the document level. The maximum TTL value is 2147483647.

At the container level, TTL needs to be set to one of the below values:

1. Does Not Exist – No TTL and no expiration even if trying to set TTL on a document.
2. -1 – No TTL by default but can be added at the document level.
3. Number of seconds – Default TTL is the provided number of seconds. This can be overridden at the document level.

Expiring documents and optimizing the storage consumed can result in better performance and lower costs. So it's important to decide which TTL value to use and which items to expire.

Some solutions may require Cosmos DB as an intermediate storage to perform queries and pass the results to the final storage. In this case, you should use TTLs to expire documents as soon as possible to minimize cost.

Cosmos DB Consumption Models

Let's take a look at the different consumption models in detail.

Serverless

In Serverless model, the service is billed according to the actual number of RUs consumed. This is great when the consumption pattern is unpredictable and can depend of factors like campaigns, feature releases, time of the day, seasonal sales, holidays, and so on.

It is also great in situations when:

1. A new application is launched and we don't have much load to start with. We also don't know how the load will grow.
2. The DB supports a serverless application hosted on Azure Functions. As the application gets more users, the DB will also get more requests.
3. Getting started with Cosmos DB and not having a lot of experience with provisioning and cost.
4. The service is not expected to scale and will likely consume less than the minimum configurable RUs.

Provisioned vs Serverless

Deciding between Serverless and Provisioned consumption model is a trade-off between cost and performance. Use the below points to help you decide:

1. The workload – predictable and sufficiently large workload favours provisioned consumption model.
2. RU limiting – Provisioned throughput will not exceed the maximum decided RU while Serverless can scale up to the maximum possible RUs/s allowed in Cosmos DB. When expecting burst situations, you can use Serverless.
3. Global Distribution – This is an important factor. Serverless models are not distributed across regions and so can be used for a single region. Provisioned models are distributed across regions and can be used for multiple regions.
4. Storage Limits – Serverless only stores 50 GB of data per container while Provisioned can store unlimited data per container.

Auto-Scale Model

Auto-Scale model finds the balance between provisioned and serverless consumption models. It works by dynamically provisioning resources as needed but within a specified range.

Let's look at a comparison between auto-scale and provisioned throughput:

1. The workload – Auto-scale throughput oscillates between the minimum acceptable performance and the maximum cost we want to incur. Provisioned is still better if the workload is predictable because we neither want to lose out on performance nor incur more costs in the long run.
2. RU consumption – With auto-scale, we can set an RU limit same as with provisioned. The difference is that provisioned billing is always done on the RUs specified but auto-scale billing is based on – the RUs consumed in real-time or 10% of the provisioned RUs – whichever is higher. Keeping this in mind, it's recommended to use provisioned consumption model only if the actual consumption is close to the provisioned limit for more than 66% of the time.

It is also possible to migrate containers from auto-scale to provisioned throughput and vice versa. During the migration, a RU value is automatically chosen by the system and must be verified or manually set after the migration.

Wrapping Up

Thanks for reading. This should give you some idea of how Azure's CosmosDB service works and how to configure it. If you want to connect with me, you can find me on Twitter.

Why Use Rate Limiting?

Let's get started with some basics to make sure we understand the need for rate limiting and introduce the tools we'll be using in this tutorial.

Problem with Unlimited Rates

If a public API like the Twitter API allowed its users to make an unlimited number of requests per hour, it could lead to:

• resource exhaustion
• decreasing quality of the service
• denial of service attacks

This might result in a situation where the service is unavailable or slow. It could also lead to more unexpected costs being incurred by the service.

How Rate Limiting Helps

Firstly, rate-limiting can prevent denial of service attacks. When coupled with a deduplication mechanism or API keys, rate limiting can also help prevent distributed denial of service attacks.

Secondly, it helps in estimating traffic. This is very important for public APIs. This can also be coupled with automated scripts to monitor and scale the service.

And thirdly, you can use it to implement tier-based pricing. This type of pricing model means that users can pay for a higher rate of requests. The Twitter API is an example of this.

The Token Bucket Algorithm

Token Bucket is an algorithm that you can use to implement rate limiting. In short, it works as follows:

1. A bucket is created with a certain capacity (number of tokens).
2. When a request comes in, the bucket is checked. If there is enough capacity, the request is allowed to proceed. Otherwise, the request is denied.
3. When a request is allowed, the capacity is reduced.
4. After a certain amount of time, the capacity is replenished.

How to Implement Token Bucket in a Distributed System

To implement the token bucket algorithm in a distributed system, we need to use a distributed cache.

The cache is a key-value store to store the bucket information. We will use a Redis cache to implement this.

Internally, Bucket4j allows us to plug in any implementation of the Java JCache API. The Redisson client of Redis is the implementation we will use.

Project Implementation

We will use the Spring Boot framework to build our service.

Our service will contain the below components:

1. A simple REST API.
2. A Redis cache connected to the service – using the Redisson client.
3. The Bucket4J library wrapped around the REST API.
4. We'll connect Bucket4J to the JCache interface which will use the Redisson client as the implementation in the background.

First, we will learn to rate limit the API for all requests. Then we will learn to implement a more complex rate limiting mechanism per user or per pricing tier.

Let's start with the project setup.

Install Dependencies

Let's add the below dependencies to our pom.xml (or build.gradle) file.

<dependencies>
    <!-- To build the Rest API -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Redisson Starter = Spring Data Redis starter(excluding other clients) and Redisson client -->
    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <version>3.17.0</version>
    </dependency>

    <!-- Bucket4J starter = Bucket4J + JCache -->
    <dependency>
        <groupId>com.giffing.bucket4j.spring.boot.starter</groupId>
        <artifactId>bucket4j-spring-boot-starter</artifactId>
        <version>0.5.2</version>
    </dependency>
</dependencies>

Cache Configuration

Firstly, we need to start our Redis server. Let's say we have a Redis server running on port 6379 on our local machine.

We need to perform two steps:

1. Create a connection to this server from our application.
2. Set up JCache to use the Redisson client as the implementation.

Redisson's documentation provides concise steps to implement this in a regular Java application. We're going to implement the same steps, but in Spring Boot.

Let's look at the code first. We need to create a Configuration class to create the required beans.

@Configuration
public class RedisConfig  {

    @Bean
    public Config config() {
        Config config = new Config();
        config.useSingleServer().setAddress("redis://localhost:6379");
        return config;
    }

    @Bean
    public CacheManager cacheManager(Config config) {
        CacheManager manager = Caching.getCachingProvider().getCacheManager();
        cacheManager.createCache("cache", RedissonConfiguration.fromConfig(config));
        return cacheManager;
    }

    @Bean
    ProxyManager<String> proxyManager(CacheManager cacheManager) {
        return new JCacheProxyManager<>(cacheManager.getCache("cache"));
    }
}

What does this do?

1. Creates a configuration object that we can use to create a connection.
2. Creates a cache manager using the configuration object. This will internally create a connection to the Redis instance and create a hash called "cache" on it.
3. Creates a proxy manager that will be used to access the cache. Whatever our application tries to cache using the JCache API, it will be cached on the Redis instance inside the hash named "cache".

Build the API

Let's create a simple REST API.

@RestController
public class RateLimitController {
    @GetMapping("/user/{id}")
    public String getInfo(@PathVariable("id") String id) {
        return "Hello " + id;
    }
}

If I hit the API with the URL http://localhost:8080/user/1, I will get the response Hello 1.

Bucket4J Configuration

To implement the rate limiting, we need to configure Bucket4J. Thankfully, we do not need to write any boilerplate code due to the starter library.

It also automatically detects the ProxyManager bean we created in the previous step and uses it to cache the buckets.

What we do need to do is configure this library around the API we created.
Again there are multiple ways to do this.

We can go for property-based configuration which is defined in the starter library.
This is the most convenient way for simple cases like rate-limiting for all users or all guest users.

However, if we want to implement something more complex like a rate limit for each user, it's better to write custom code for it.

We are going to implement rate limiting per user. Let's assume we have the rate limit for each user stored in a database, and we can query it using the user id.

Let's write the code for it step by step.

Create a Bucket

Before we start, let's look at how a bucket is created.

Refill refill = Refill.intervally(10, Duration.ofMinutes(1));
Bandwidth limit = Bandwidth.classic(10, refill);
Bucket bucket = Bucket4j.builder()
        .addLimit(limit)
        .build();

• Refill – After how much time the bucket will be refilled.
• Bandwidth – How much bandwidth the bucket has. Basically, requests per refill period.
• Bucket – An object configured using these two parameters. Additionally, it maintains a token counter to keep track of how many tokens are available in the bucket.

Using this as the building block, let's change a few things to make it suitable to our use case.

Create and Cache Buckets using ProxyManager

We created the proxy manager for the purpose of storing buckets on Redis. Once a bucket is created, it needs to be cached on Redis and does not need to be created again.

To make this happen, we will replace the Bucket4j.builder() with proxyManager.builder(). ProxyManager will take care of caching the buckets and not creating them again.

ProxyManager's builder takes two parameters – a key against which the bucket will be cached and a configuration object that it will use to create the bucket.

Let's see how we can implement it:

@Service
public class RateLimiter {
    //autowiring dependencies

    public Bucket resolveBucket(String key) {
        Supplier<BucketConfiguration> configSupplier = getConfigSupplierForUser(key);

        // Does not always create a new bucket, but instead returns the existing one if it exists.
        return buckets.builder().build(key, configSupplier);
    }

    private Supplier<BucketConfiguration> getConfigSupplierForUser(String key) {
        User user = userRepository.findById(userId);
        Refill refill = Refill.intervally(user.getLimit(), Duration.ofMinutes(1));
        Bandwidth limit = Bandwidth.classic(user.getLimit(), refill);
        return () -> (BucketConfiguration.builder()
                .addLimit(limit)
                .build());
    }
}

We have created a method which returns a bucket for a key provided. In the next step, we will see how to use this.

How to Consume Tokens and Set Up Rate Limiting

When a request comes in, we will try to consume a token from the relevant bucket.
We will use the tryConsume() method of the bucket to do this.

@GetMapping("/user/{id}")
public String getInfo(@PathVariable("id") String id) {
    // gets the bucket for the user
    Bucket bucket = rateLimiter.resolveBucket(id);

    // tries to consume a token from the bucket
    if (bucket.tryConsume(1)) {
        return "Hello " + id;
    } else {
        return "Rate limit exceeded";
    }
}

The tryConsume() method returns true if the token was consumed successfully or false if the token was not consumed.

How to Test our Service

We can test this using any automated testing technique. For example, we can use JUnit. Let's write a test case that calls the getInfo() method multiple times and verifies that the response is correct.

Let's assume we have a user with id 1 and a limit of 10 requests per minute. Let's assume we also have a user with id 2 and a limit of 20 requests per minute.

We will hit 11 requests for both users and verify that the request fails for the user with id 1 but succeeds for the user with id 2.

@Test
public void testGetInfo() {

    // calls the method 10 times for user 1
    for (int i = 0; i < 10; i++) {
        rateLimiter.getInfo(1));
        rateLimiter.getInfo(2));
    }

    // verifies that the response is rate limited for user 1
    assertEquals("Rate limit exceeded", rateLimiter.getInfo(1));

    // verifies that the response is successful for user 2
    assertEquals("Hello 2", rateLimiter.getInfo(2));
}

When we run the test, we will see that the test passes.

Conclusion

In this tutorial, we have covered how to create a rate limiter using Bucket4j and Redis in a Spring Boot application.We also looked at how to set up a Redisson client with JCache and how to use it to cache buckets.

At the end, we implemented a simple rate limiter which can be used to rate limit requests for specific users.

Hope you enjoyed this tutorial. Thanks for reading!