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}") 
public User getUser(@PathVariable UUID userId) {
        [implementation deleted]
}

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:

@Test 
public void shouldGetUser() { 
    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");
// or
FriendlyIds.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
@RestController
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @GetMapping("/bars/{bar}")
    public Bar getBar(@PathVariable UUID bar) {
        return new Bar(UUID.randomUUID());
    }

    @Value
    class Bar {
        private final UUID id;
    }
}  

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:

ObjectMapper mapper = new ObjectMapper()
   .registerModule(new FriendlyIdModule());

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:

@Entity
public class User {
    @Id
    private FriendlyId id;
    
    private String name;
    
    // 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")
public interface UserClient {
    
    @GetMapping("/users/{id}")
    UserDto getUser(@PathVariable UUID id); // Sends FriendlyId string
    
    @GetMapping("/users/{id}/profile")
    ProfileDto getProfile(@PathVariable FriendlyId id); // 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:

ObjectMapper mapper = new ObjectMapper()
   .registerModule(new FriendlyIdJackson2Module());

Utility class renamed

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

// Before (1.x)
import com.devskiller.friendly_id.FriendlyId;
FriendlyId.toUuid("5wbwf6yUxVBcr48AMbz9cb");

// After (2.x)
import com.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)
import com.devskiller.friendly_id.jackson.IdFormat;
import com.devskiller.friendly_id.jackson.FriendlyIdFormat;

// After (2.x)
import com.devskiller.friendly_id.IdFormat;
import com.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:

import com.devskiller.friendly_id.type.FriendlyId;

// Create from UUID
FriendlyId id = FriendlyId.of(uuid);

// Or use static import friendly method
import static com.devskiller.friendly_id.type.FriendlyId.friendlyId;
FriendlyId id = friendlyId(uuid);

// Parse from string (accepts both FriendlyId and UUID formats)
FriendlyId id = FriendlyId.parse("5wbwf6yUxVBcr48AMbz9cb");
FriendlyId id = FriendlyId.parse("c3587ec5-0976-497f-8374-61e0c2ea3da5");

// Create random
FriendlyId id = FriendlyId.random();

// Get UUID
UUID uuid = id.toUuid();

// Get string representation
String friendlyIdString = id.value();      // Returns FriendlyId string
String friendlyIdString = 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.