FriendlyID (Java, Swift, Rust, Go)

What is the FriendlyID library?

The FriendlyID library converts a given UUID (with 36 characters) to a URL-friendly ID (a "FriendlyID") which is based on Base62 (with a maximum of 22 characters), as in the example below:

UUID Friendly ID
c3587ec5-0976-497f-8374-61e0c2ea3da5 -> 5wbwf6yUxVBcr48AMbz9cb
| | 36 characters 22 characters or less

In addition, this library allows to:

• convert from a FriendlyID back to the original UUID; and
• create a new, random FriendlyID

Why use a FriendlyID?

Universal Unique IDs (UUIDs) provide a non-sequential and unique identifier that can be generated separately from the source database. As a result, it is not possible to guess either the previous or next identifier. That's great, but, to achieve this level of security, a UUID is long (128 bits long) and looks ugly (36 alphanumeric characters including four hyphens which are added to make it easier to read the UUID), as in this example: 123e4567-e89b-12d3-a456-426655440000.

Such a format is:

• difficult to read (especially if it is part of a URL)
• difficult to remember
• cannot be copied with just two mouse-clicks (you have to select manually the start and end positions)
• can easily become broken across lines when it is copied, pasted, edited, or sent.

Our FriendlyID Java library solves these problems by converting a given UUID using Base62 with alphanumeric characters in the range [0-9A-Za-z] into a FriendlyId which consists of a maximum of 22 characters (but in fact often contains fewer characters).

Supported languages

Curently FriendlyId supports Java (this project) and

• Swift language (thanks to Kevin Wooten)
• Rust
• Go

Tools

There are available CLI converters for many platforms.

• https://github.com/mariuszs/rust-friendlyid (also available in RPM and DEB format)
• https://github.com/kdubb/SwiftFriendlyId#command-line

Use cases

Basic (returning a user in a database)

Let us assume that a method in the controller for returning users requires the relevant UUID in order to find a given user in a database, as in this example:

@GetMapping("/users/{userId}") publicUsergetUser(@PathVariableUUIDuserId) {
[implementationdeleted]
}

Without using the Friendly ID library, you could access a given user as follows:

curl http://localhost:8080/users/c3587ec5-0976-497f-8374-61e0c2ea3da5

After adding the FriendlyID library, the controller method itself does not change, but you would be able to access a given user using the relevant FriendlyID as follows:

curl http://localhost:8080/users/5wbwf6yUxVBcr48AMbz9cb

In addition, if a given document returned by such a method contains objects of type UUID, those IDs will also be shortened into FriendlyID format.

Advanced (Optimizing testing)

The FriendlyID library makes it possible to define for UUIDs values which are easy to read. By using names instead of hard-to-remember UUIDs, you can write much simpler tests for your code, for example:

@TestpublicvoidshouldGetUser() { mockMvc.perform(get("/users/{userId}", "John")) .andExpect(status().isOk()) .andExpect(content().contentType("application/json")) .andExpect(jsonPath("$.uuid", is("John"))); } 

In the above example, the variable "John" is decoded by the library to the correct UUID, in this case, 00000000-0000-0000-0000-000000a69efb. In this way, you can give a variable in a test class a truly meaningful value and, as a result, an assertion which refers to that variable becomes exceptionally easy to understand in your test program.

FriendlyID library

Dependencies

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id</artifactId>
<version>2.0.0-beta3</version>
</dependency>

Usage

FriendlyIds.createFriendlyId();

This creates a new, random FriendlyID, for example: 5wbwf6yUxVBcr48AMbz9cb

FriendlyIds.toFriendlyId(UUID.fromString("c3587ec5-0976-497f-8374-61e0c2ea3da5"));

This converts a UUID in the form of a string to a FriendlyID, for example: 5wbwf6yUxVBcr48AMbz9cb

FriendlyIds.toUuid("5wbwf6yUxVBcr48AMbz9cb");
// orFriendlyIds.toUuid("c3587ec5-0976-497f-8374-61e0c2ea3da5");

This converts a FriendlyID or UUID string to UUID. Both formats are accepted.

Notes

• As every UUID is a 128-bit number, a FriendlyID can also store only a 128-bit number.
• If a FriendlyID has any leading zeros, those leading zeros are ignored - for example, 00cafe is treated as cafe.

Integrations

• Spring Boot integration
• Jackson integration
• jOOQ integration
• JPA integration
• OpenFeign integration

Spring Boot integration

The FriendlyID library includes a Spring configuration to make it easy to add shorter IDs to an application. With a typical application based on Spring Boot, for your controllers to be able to use FriendlyIDs when communicating with the outside world, just add one new starter dependency as follows:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-spring-boot-starter</artifactId>
<version>2.0.0-beta3</version>
</dependency>

Let us assume that you'll use this sample application:

@SpringBootApplication@RestControllerpublicclassApplication {
publicstaticvoidmain(String[] args) {
SpringApplication.run(Application.class, args);
}
@GetMapping("/bars/{bar}")
publicBargetBar(@PathVariableUUIDbar) {
returnnewBar(UUID.randomUUID());
}
@ValueclassBar {
privatefinalUUIDid;
}
} 

This command: curl http://localhost:8080/bars/5fD1KwsxRcGhBqWNju0jzt

will result in the following output:

{"id":"52OMXhWiAqUWwII0c97Svl"}

In this case, Bar is a POJO class which is converted by Spring MVC to a JSON document. This Bar object has one field of type UUID, and this field is output to the JSON document as a FriendlyID instead of a UUID. Although the application uses the relevant UUID internally, from an external point of view, only the FriendlyID is visible.

Jackson integration

First, add the following Jackson module dependency:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-jackson-datatype</artifactId>
<version>2.0.0-beta3</version>
</dependency>

Then register the FriendlyIdModule module as follows:

ObjectMappermapper = newObjectMapper()
.registerModule(newFriendlyIdModule());

jOOQ integration

The FriendlyID library provides a jOOQ converter for seamless integration with jOOQ's code generation and type-safe queries.

First, add the dependency:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-jooq</artifactId>
<version>2.0.0-beta3</version>
</dependency>

Configure the converter in your jOOQ code generation configuration:

<forcedTypes>
<forcedType>
<userType>com.devskiller.friendly_id.type.FriendlyId</userType>
<converter>com.devskiller.friendly_id.jooq.FriendlyIdConverter</converter>
<includeExpression>.*\.id</includeExpression>
<includeTypes>UUID</includeTypes>
</forcedType>
</forcedTypes>

This automatically converts UUID database columns to FriendlyId value objects in your generated jOOQ records.

JPA integration

The FriendlyID library includes a JPA AttributeConverter for transparent conversion between UUID database columns and FriendlyId value objects.

First, add the dependency:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-jpa</artifactId>
<version>2.0.0-beta3</version>
</dependency>

The converter is automatically applied to all FriendlyId attributes in your entities:

@EntitypublicclassUser {
@IdprivateFriendlyIdid;
privateStringname;
// getters/setters
}

The FriendlyId value object stores UUID internally (16 bytes) and computes the FriendlyId string only when needed, making it more memory-efficient than storing strings.

OpenFeign integration

The FriendlyID library provides automatic encoding/decoding for Spring Cloud OpenFeign clients.

First, add the dependency:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-openfeign</artifactId>
<version>2.0.0-beta3</version>
</dependency>

The integration is automatically configured when Spring Cloud OpenFeign is on the classpath:

@FeignClient(name = "user-service")
publicinterfaceUserClient {
@GetMapping("/users/{id}")
UserDtogetUser(@PathVariableUUIDid); // Sends FriendlyId string@GetMapping("/users/{id}/profile")
ProfileDtogetProfile(@PathVariableFriendlyIdid); // Also works with FriendlyId value object
}

UUID and FriendlyId parameters are automatically converted to FriendlyId strings in requests, and FriendlyId strings in responses are converted back to UUID or FriendlyId objects.

Migration Guide

Migrating from 1.x to 2.x

Version 2.0 introduces several breaking changes to support Spring Boot 4 and Jackson 3.

Requirements

Version	Java	Spring Boot	Jackson
1.x	8+	2.x, 3.x	2.x
2.x	21+	4.x	3.x

For Spring Boot 4 + Jackson 3 projects

Update dependencies to use the new version:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-spring-boot-starter</artifactId>
<version>2.0.0-beta3</version>
</dependency>

For Spring Boot 3 + Jackson 2 projects

Use the new Jackson 2.x module:

<dependency>
<groupId>com.devskiller.friendly-id</groupId>
<artifactId>friendly-id-jackson2-datatype</artifactId>
<version>2.0.0-beta3</version>
</dependency>

Register the module:

ObjectMappermapper = newObjectMapper()
.registerModule(newFriendlyIdJackson2Module());

Utility class renamed

The utility class has been renamed from FriendlyId to FriendlyIds (plural) following Java conventions:

// Before (1.x)importcom.devskiller.friendly_id.FriendlyId;
FriendlyId.toUuid("5wbwf6yUxVBcr48AMbz9cb");
// After (2.x)importcom.devskiller.friendly_id.FriendlyIds;
FriendlyIds.toUuid("5wbwf6yUxVBcr48AMbz9cb");

The old FriendlyId class is deprecated and will be removed in a future version.

@IdFormat annotation

The @IdFormat annotation has been moved from the Jackson module to the core module:

// Before (1.x)importcom.devskiller.friendly_id.jackson.IdFormat;
importcom.devskiller.friendly_id.jackson.FriendlyIdFormat;
// After (2.x)importcom.devskiller.friendly_id.IdFormat;
importcom.devskiller.friendly_id.FriendlyIdFormat;

This change allows using the same annotation with both Jackson 2.x and Jackson 3.x modules.

FriendlyId value object

Version 2.x introduces the FriendlyId value object type for type-safe ID handling:

importcom.devskiller.friendly_id.type.FriendlyId;
// Create from UUIDFriendlyIdid = FriendlyId.of(uuid);
// Or use static import friendly methodimportstaticcom.devskiller.friendly_id.type.FriendlyId.friendlyId;
FriendlyIdid = friendlyId(uuid);
// Parse from string (accepts both FriendlyId and UUID formats)FriendlyIdid = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
FriendlyIdid = FriendlyId.parse("c3587ec5-0976-497f-8374-61e0c2ea3da5");
// Create randomFriendlyIdid = FriendlyId.random();
// Get UUIDUUIDuuid = id.toUuid();
// Get string representationStringfriendlyIdString = id.value(); // Returns FriendlyId stringStringfriendlyIdString = id.toString(); // Same as value()

The value object can be used in:

• @PathVariable FriendlyId id
• @RequestParam FriendlyId id
• @RequestBody with JSON fields
• JPA entities
• jOOQ records

Null-safety with JSpecify

Version 2.x uses JSpecify annotations for null-safety. All packages are marked with @NullMarked, meaning parameters and return values are non-null by default.

Jackson module names

Jackson Version	Module Class	Artifact
Jackson 3.x	FriendlyIdModule	friendly-id-jackson-datatype
Jackson 2.x	FriendlyIdJackson2Module	friendly-id-jackson2-datatype

Contributing

Thinking of helping us out? We invite you to take a look at:

• Source Code: github.com/Devskiller/friendly-id/
• Issue Tracker: github.com/Devskiller/friendly-id/issues

License

The project is licensed under the Apache 2.0 license. For further details, please see the License page.