Java Friendly Id for UUID
Switch branches/tags
Clone or download
Latest commit 0f02c2e Aug 30, 2018

Build Status Maven Central

friendly ID

Library to convert UUID to url friendly IDs basing on Base62

UUID                                        Friendly ID

c3587ec5-0976-497f-8374-61e0c2ea3da5   ->   7NLCAyd6sKR7kDHxgAWFPG
|                                           |                              
36 characters                               22 characters

Spring Boot integration

Just add friendly-id starter dependency:


Sample application:

public class Application {

    public static void main(String[] args) {, args);

    public Bar getBar(@PathVariable UUID bar) {
        return new Bar(UUID.randomUUID());

    class Bar {
        private final UUID id;


curl 'localhost:8080/bars/5fD1KwsxRcGhBqWNju0jzt' 

Application uses internally UUID, but from external point of view only friendly id is visible.

Testing improvments

This allows to write much simpler tests for our code, because you can use names instead of hard to remember UUIDs.

mockMvc.perform(get("/bars/{bar}", "sampleBar"))
  .andExpect(jsonPath("$._links.self.href", is("http://localhost/bars/sampleBar")));

There is no need to define UUID value for bar, sampleBar is decoded to valid UUID identifier.

FriendlyID library





// c3587ec5-0976-497f-8374-61e0c2ea3da5



  • Id 00cafe is equal to cafe - leading zeros are ignored.
  • UUID is a 128-bit number, so id also can store only 128-bit number

Jackson integration

Add jackson module dependency:


Register friendly_id module:

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