1. Overview
In this article we’ll start exploring the JSON-API spec and how that can be integrated into a Java backed REST API. We are also using some minor Spring annotations but these can easily be taken out to make the project fully independent of Spring.
We’ll use the Katharsis implementation of JSON-API in Java – and we’ll set up a Katharsis powered Servlet – so all we need is a servlet-based application.
2. Maven
First, let’s take a look at our maven configuration – we need to add the following dependency into our pom.xml:
<dependency>
<groupId>io.katharsis</groupId>
<artifactId>katharsis-servlet</artifactId>
<version>1.0.0</version>
</dependency>
3. A User Resource
Next, let’s take a look at our User resource:
@JsonApiResource(type = "users")
public class User {
@JsonApiId
private Long id;
private String name;
private String email;
}
Note that:
- @JsonApiResource annotation is used to define our resource User
- @JsonApiId annotation is used to define the resource identifier
And very briefly – the persistence for this example is going to be a Spring Data repository here (but of course it doesn’t have to be):
public interface UserRepository extends JpaRepository<User, Long> {}
4. A Resource Repository
Next, let’s discuss our resource repository – each resource should have a ResourceRepository to publish the API operations available on it:
@Component
public class UserResourceRepository implements ResourceRepository<User, Long> {
@Autowired
private UserRepository userRepository;
@Override
public User findOne(Long id, RequestParams params) {
return userRepository.findOne(id);
}
@Override
public Iterable<User> findAll(RequestParams params) {
return userRepository.findAll();
}
@Override
public Iterable<User> findAll(Iterable<Long> ids, RequestParams params) {
return userRepository.findAll(ids);
}
@Override
public <S extends User> S save(S entity) {
return userRepository.save(entity);
}
@Override
public void delete(Long id) {
userRepository.delete(id);
}
}
A quick note here – if you’re used to a Spring style of application, than this is of course very similar to a Spring controller.
5. Katharsis Filter
As we are using a katharsis-servlet – so we’ll need to implement a filter by extending the AbstractKatharsisFilter:
@Component
public class JsonApiFilter extends AbstractKatharsisFilter implements BeanFactoryAware {
private static final String DEFAULT_RESOURCE_SEARCH_PACKAGE = "org.baeldung.persistence";
private static final String RESOURCE_DEFAULT_DOMAIN = "http://localhost:8080";
private BeanFactory beanFactory;
@Override
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
this.beanFactory = beanFactory;
}
@Override
protected KatharsisInvokerBuilder createKatharsisInvokerBuilder() {
KatharsisInvokerBuilder builder = new KatharsisInvokerBuilder();
builder.resourceSearchPackage(DEFAULT_RESOURCE_SEARCH_PACKAGE).
resourceDefaultDomain(RESOURCE_DEFAULT_DOMAIN).
jsonServiceLocator(new JsonServiceLocator() {
@Override
public <T> T getInstance(Class<T> clazz) {
return beanFactory.getBean(clazz);
}
});
return builder;
}
}
Notice that – in this case, we are using a few minor Spring related artifacts – turning this filter into a bean – just so that it can play well in a Spring enabled system.
Also note how we only need to override the createKatharsisInvokerBuilder() method – based on our project configuration.
With that – we can now start consuming the API; for example:
- GET “http://localhost:8080/users“: to get all users.
- POST “http://localhost:8080/users“: to add new user, and more.
6. Relationships
Next, let’s discuss how to handle entities relationships in our JSON API.
6.1. Role Resource
First, let’s introduce a new resource – Role:
@JsonApiResource(type = "roles")
public class Role {
@JsonApiId
private Long id;
private String name;
@JsonApiToMany
private Set<User> users;
}
And then set up a many-to-many relation between User and Role:
@JsonApiToMany @JsonApiIncludeByDefault private Set<Role> roles;
6.2. Role Resource Repository
Very quickly – here is our Role resource repository:
@Component
public class RoleResourceRepository implements ResourceRepository<Role, Long> {
@Autowired
private RoleRepository roleRepository;
@Override
public Role findOne(Long id, RequestParams params) {
return roleRepository.findOne(id);
}
@Override
public Iterable<Role> findAll(RequestParams params) {
return roleRepository.findAll();
}
@Override
public Iterable<Role> findAll(Iterable<Long> ids, RequestParams params) {
return roleRepository.findAll(ids);
}
@Override
public <S extends Role> S save(S entity) {
return roleRepository.save(entity);
}
@Override
public void delete(Long id) {
roleRepository.delete(id);
}
}
It is important to understand here is that this single resource repo doesn’t handle the relationship aspect – that takes a separate repository.
6.3. Relationship Repository
In order to handle many-to-many relationship between User–Role we need to create a new style of repository:
@Component
public class UserToRoleRelationshipRepository
implements RelationshipRepository<User, Long, Role, Long> {
@Autowired
private UserRepository userRepository;
@Autowired
private RoleRepository roleRepository;
@Override
public void setRelation(User User, Long roleId, String fieldName) { }
@Override
public void setRelations(User user, Iterable<Long> roleIds, String fieldName) {
Set<Role> roles = new HashSet<Role>();
roles.addAll(roleRepository.findAll(roleIds));
user.setRoles(roles);
userRepository.save(user);
}
@Override
public void addRelations(User user, Iterable<Long> roleIds, String fieldName) {
Set<Role> roles = user.getRoles();
roles.addAll(roleRepository.findAll(roleIds));
user.setRoles(roles);
userRepository.save(user);
}
@Override
public void removeRelations(User user, Iterable<Long> roleIds, String fieldName) {
Set<Role> roles = user.getRoles();
roles.removeAll(roleRepository.findAll(roleIds));
user.setRoles(roles);
userRepository.save(user);
}
@Override
public Role findOneTarget(
Long sourceId, String fieldName, RequestParams requestParams) {
return null;
}
@Override
public Iterable<Role> findManyTargets(
Long sourceId, String fieldName, RequestParams requestParams) {
User user = userRepository.findOne(sourceId);
return user.getRoles();
}
}
We’re ignoring the singular methods here, in the relationship repository.
7. Test
Finally, let’s analyze a few requests and really understand what the JSON-API output looks like.
We’re going to start retrieving a single User resource (with id = 2):
GET http://localhost:8080/users/2
{
"data":{
"type":"users",
"id":"2",
"attributes":{
"email":"tom@test.com",
"username":"tom"
},
"relationships":{
"roles":{
"links":{
"self":"http://localhost:8080/users/2/relationships/roles",
"related":"http://localhost:8080/users/2/roles"
}
}
},
"links":{
"self":"http://localhost:8080/users/2"
}
},
"included":[
{
"type":"roles",
"id":"1",
"attributes":{
"name":"ROLE_USER"
},
"relationships":{
"users":{
"links":{
"self":"http://localhost:8080/roles/1/relationships/users",
"related":"http://localhost:8080/roles/1/users"
}
}
},
"links":{
"self":"http://localhost:8080/roles/1"
}
}
]
}
Take-aways:
- The main attributes of the Resource are found in data.attributes
- The main relationships of the Resource are found in data.relationships
- As we used @JsonApiIncludeByDefault for the roles relationship, it is included in the JSON and found in node included
Next – let’s get the collection resource containing the Roles:
GET http://localhost:8080/roles
{
"data":[
{
"type":"roles",
"id":"1",
"attributes":{
"name":"ROLE_USER"
},
"relationships":{
"users":{
"links":{
"self":"http://localhost:8080/roles/1/relationships/users",
"related":"http://localhost:8080/roles/1/users"
}
}
},
"links":{
"self":"http://localhost:8080/roles/1"
}
},
{
"type":"roles",
"id":"2",
"attributes":{
"name":"ROLE_ADMIN"
},
"relationships":{
"users":{
"links":{
"self":"http://localhost:8080/roles/2/relationships/users",
"related":"http://localhost:8080/roles/2/users"
}
}
},
"links":{
"self":"http://localhost:8080/roles/2"
}
}
],
"included":[
]
}
The quick take-away here is that we get all Roles in the system – as an array in the data node
8. Conclusion
JSON-API is a fantastic spec – finally adding some structure in the way we use JSON in our APIs and really powering a true Hypermedia API.
This piece explored one way to set it up in a web app. We’ll definitely explore other way – perhaps more idiomatic to Spring – in the future. But regardless of that implementation, the spec itself is – in my view – very very promising work.
The complete source code for the example is available in this github project. It is a Maven project which can be imported and run as-is.