Projections and Excerpts in Spring Data REST

1. Overview 

In this article – we’ll explore Spring Data REST’s concepts of projections and excerpts.

We’ll learn how to use projections to create custom views of our models and how to use excerpts as default views to resource collections.

2. Our Domain Models

First, let’s start by defining our domain models: Book and Author.

Let’s have a look at the Book entity class:

@Entity
public class Book {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private long id;

    @Column(nullable = false)
    private String title;
    
    private String isbn;

    @ManyToMany(mappedBy = "books", fetch = FetchType.EAGER)
    private List<Author> authors;
}

And the Author model:

@Entity
public class Author {

    @Id
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private long id;

    @Column(nullable = false)
    private String name;

    @ManyToMany(cascade = CascadeType.ALL)
    @JoinTable(
      name = "book_author", 
      joinColumns = @JoinColumn(
        name = "book_id", referencedColumnName = "id"), 
      inverseJoinColumns = @JoinColumn(
        name = "author_id", referencedColumnName = "id"))
    private List<Book> books;
}

The two entities also have a many-to-many relationship.

Next, let’s define standard Spring Data REST repositories for each of the models:

public interface BookRepository extends CrudRepository<Book, Long> {}

public interface AuthorRepository extends CrudRepository<Author, Long> {}

Now, we can access Book endpoint to get a specific Book’s details using its id at http://localhost:8080/books/{id}:

{
  "title" : "Animal Farm",
  "isbn" : "978-1943138425",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/books/1"
    },
    "book" : {
      "href" : "http://localhost:8080/books/1"
    },
    "authors" : {
      "href" : "http://localhost:8080/books/1/authors"
    }
  }
}

Note that since the Author model has its repository, authors details aren’t part of the response. We can, however, find the link to them – http://localhost:8080/books/1/authors.

3. Creating a Projection

Sometimes, we’re only interested in a subset or a custom view of an entity’s attributes. For such cases, we can make use of projections.

Let’s create a custom view to our Book using Spring Data REST projections.

We’ll start by creating a simple Projection called CustomBook:

@Projection(
  name = "customBook", 
  types = { Book.class }) 
public interface CustomBook { 
    String getTitle();
}

Note that our projection is defined as an interface with an @Projection annotation. We can use the name attribute to customize the name of the projection, as well as the types attributes to define the objects it applies to.

In our example, the CustomBook projection will only include the title of a book.

Let’s have a look again at our Book representation after creating our Projection:

{
  "title" : "Animal Farm",
  "isbn" : "978-1943138425",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/books/1"
    },
    "book" : {
      "href" : "http://localhost:8080/books/1{?projection}",
      "templated" : true
    },
    "authors" : {
      "href" : "http://localhost:8080/books/1/authors"
    }
  }
}

Great, we can see a link to our projection. Let’s check the view we created at http://localhost:8080/books/1?projection=customBook:

{
  "title" : "Animal Farm",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/books/1"
    },
    "book" : {
      "href" : "http://localhost:8080/books/1{?projection}",
      "templated" : true
    },
    "authors" : {
      "href" : "http://localhost:8080/books/1/authors"
    }
  }
}

Here, we can see that we only get the title field, while the isbn is no longer present in the custom view.

As a general rule, we can access a projection’s result at http://localhost:8080/books/1?projection={projection name}.

Also, note that we need to define our Projection in the same package as our models. Alternatively, we can use RepositoryRestConfigurerAdapter to add it explicitly:

@Configuration
public class RestConfig extends RepositoryRestConfigurerAdapter {
 
    @Override
    public void configureRepositoryRestConfiguration(
      RepositoryRestConfiguration repositoryRestConfiguration) {
        repositoryRestConfiguration.getProjectionConfiguration()
          .addProjection(CustomBook.class);
    }
}

4. Adding New Data to Projections

Now, let’s see how to add new data to our projection.

As we discussed in the previous section, we can use a Projection to select which attributes to include in our view. What’s more, we can also add data that are not included in the original view.

4.1. Hidden Data

By default, ids are not included in the original resource view.

To see the ids in the result, we can include the id field explicitly:

@Projection(
  name = "customBook", 
  types = { Book.class }) 
public interface CustomBook {
    @Value("#{target.id}")
    long getId(); 
    
    String getTitle();
}

Now the output at http://localhost:8080/books/1?projection={projection name} will be:

{
  "id" : 1,
  "title" : "Animal Farm",
  "_links" : {
     ...
  }
}

Note that we can also include data that were hidden from the original view with @JsonIgnore.

4.2. Calculated Data

We can also include new data calculated from our resource attributes.

For example, we can include the authors count in our Projection:

@Projection(name = "customBook", types = { Book.class }) 
public interface CustomBook {
 
    @Value("#{target.id}")
    long getId(); 
    
    String getTitle();
        
    @Value("#{target.getAuthors().size()}")
    int getAuthorCount();
}

And we can check it at http://localhost:8080/books/1?projection=customBook:

{
  "id" : 1,
  "title" : "Animal Farm",
  "authorCount" : 1,
  "_links" : {
     ...
  }
}

4.3. Easy Access to Related Resources

Finally, if we usually need to access related resources – like in our example a book’s authors, we can avoid the extra request by including it explicitly:

@Projection(
  name = "customBook", 
  types = { Book.class }) 
public interface CustomBook {
 
    @Value("#{target.id}")
    long getId(); 
    
    String getTitle();
    
    List<Author> getAuthors();
    
    @Value("#{target.getAuthors().size()}")
    int getAuthorCount();
}

And the final Projection output will be:

{
  "id" : 1,
  "title" : "Animal Farm",
  "authors" : [ {
    "name" : "George Orwell"
  } ],
  "authorCount" : 1,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/books/1"
    },
    "book" : {
      "href" : "http://localhost:8080/books/1{?projection}",
      "templated" : true
    },
    "authors" : {
      "href" : "http://localhost:8080/books/1/authors"
    }
  }
}

Next, we’ll take a look at Excerpts.

5. Excerpts

Excerpts are projections which we apply as default views to resource collections.

Let’s customize our BookRepository to use the customBook Projection automatically for the collection response.

To achieve this, we’ll use the excerptProjection attribute of the @RepositoryRestResource annotation:

@RepositoryRestResource(excerptProjection = CustomBook.class)
public interface BookRepository extends CrudRepository<Book, Long> {}

Now we can make sure that customBook is the default view for the books collection by calling http://localhost:8080/books:

{
  "_embedded" : {
    "books" : [ {
      "id" : 1,
      "title" : "Animal Farm",
      "authors" : [ {
        "name" : "George Orwell"
      } ],
      "authorCount" : 1,
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/books/1"
        },
        "book" : {
          "href" : "http://localhost:8080/books/1{?projection}",
          "templated" : true
        },
        "authors" : {
          "href" : "http://localhost:8080/books/1/authors"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/books"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/books"
    }
  }
}

The same applies to viewing books by a specific author at http://localhost:8080/authors/1/books:

{
  "_embedded" : {
    "books" : [ {
      "id" : 1,
      "authors" : [ {
        "name" : "George Orwell"
      } ],
      "authorCount" : 1,
      "title" : "Animal Farm",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/books/1"
        },
        "book" : {
          "href" : "http://localhost:8080/books/1{?projection}",
          "templated" : true
        },
        "authors" : {
          "href" : "http://localhost:8080/books/1/authors"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/authors/1/books"
    }
  }
}

As mentioned, excerpts apply automatically only to collection resources. For a single resource, we have to use the projection parameter as shown in the previous sections.

This is because if we apply the Projections as the default view for single resources, it will make it difficult to know how to update the resource from a partial view.

As a final note, it’s important to remember that projections and excerpts are meant for the read-only purpose.

6. Conclusion

We learned how to use Spring Data REST projections to create custom views of our models. We also learned how to use excerpts as default views to resource collections.

The full source code for the examples can be found over on GitHub.