JSON API is a specification for building APIs using JSON. It details how clients should request resources to be fetched or modified, and how servers should respond to those requests. JSON API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers.

Katharsis is a Java library that implements the JSON API specification. It is an additional layer that can be plugged on top of existing server-side Java implementations in order to provide easy HATEOAS support. Katharsis defines resources which can be shared over a RESTful interface and a repository for handling them.

The below tutorial details how to configure and build a RESTful Hello World API that complies to the JSON API specification. Frameworks used are Katharsis, OkHttp, Spring Boot and Maven.

Tools used:

• Katharsis 3.0.
• OkHttp 3.6.
• Spring Boot 1.5.
• Maven 3.5.

General Project Setup

The example will be built and run using Apache Maven. In order to use the Katharsis framework, we need to include the katharsis-core dependency. As Spring Boot will be used for running the server part we also need to include katharsis-spring. For implementing the client part, the katharsis-client dependency is needed.

Katharsis aims to have as few dependencies as possible, and as such an HTTP client library is not included by default. It needs to be provided on the classpath where it will be automatically picked up by the framework. Both OkHttp and Apache Http Client are supported. For this example, we will use the okhttp library.

Running and testing of the example is based on the spring-boot-starter and spring-boot-starter-testSpring Boot starters. The spring-boot-maven-plugin is used to spin up an embedded Tomcat server that will host the RESTful Hello World API.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.codenotfound</groupId>
  <artifactId>json-api-katharsis-helloworld</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <name>json-api-katharsis-helloworld</name>
  <description>JSON API - Katharsis Spring Boot Hello World Example</description>
  <url>https://www.codenotfound.com/2017/04/json-api-katharsis-spring-boot-example.html</url>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.2.RELEASE</version>
  </parent>

  <properties>
    <java.version>1.8</java.version>

    <katharsis.version>3.0.1</katharsis.version>
    <okhttp.version>3.6.0</okhttp.version>
  </properties>

  <dependencies>
    <!-- spring-boot -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- katharsis -->
    <dependency>
      <groupId>io.katharsis</groupId>
      <artifactId>katharsis-core</artifactId>
      <version>${katharsis.version}</version>
    </dependency>
    <dependency>
      <groupId>io.katharsis</groupId>
      <artifactId>katharsis-spring</artifactId>
      <version>${katharsis.version}</version>
    </dependency>
    <dependency>
      <groupId>io.katharsis</groupId>
      <artifactId>katharsis-client</artifactId>
      <version>${katharsis.version}</version>
    </dependency>
    <!-- okhttp -->
    <dependency>
      <groupId>com.squareup.okhttp3</groupId>
      <artifactId>okhttp</artifactId>
      <version>${okhttp.version}</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <!-- spring-boot-maven-plugin -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

Spring Boot is used in order to make a stand-alone Katharsis example application that we can "just run." The SpringKatharsisApplication class contains the main() method that uses Spring Boot’s SpringApplication.run() method to launch the application.

The @SpringBootApplication annotation is a convenience annotation that adds: @Configuration, @EnableAutoConfiguration and @ComponentScan.

package com.codenotfound.katharsis;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringKatharsisApplication {

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

Creating the Domain Model

We start by defining a simple model that will represent a Greeting resource. It contains an id in addition to the actual greeting content. We also need to define the constructors and getters/setters for the two fields.

The @JsonApiResource annotation defines a resource. It requires the type parameter to be set which will be used to form the URI and populate the type field, which is passed as part of the resource object. According to JSON API standard, the name defined in type can be either plural or singular. However, the same value should be used consistently throughout an implementation.

The @JsonApiIddefines a field which will be used as an identifier of the Greeting resource. Each resource requires this annotation to be present on a field which is of primitive type or a type that implements the Serializable interface.

package com.codenotfound.katharsis.domain.model;

import io.katharsis.resource.annotations.JsonApiId;
import io.katharsis.resource.annotations.JsonApiResource;

@JsonApiResource(type = "greetings")
public class Greeting {

  @JsonApiId
  private long id;

  private String content;

  public Greeting() {
    super();
  }

  public Greeting(long id, String content) {
    this.id = id;
    this.content = content;
  }

  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  public String getContent() {
    return content;
  }

  public void setContent(String content) {
    this.content = content;
  }
}

Creating the Repository

To allow Katharsis to operate on defined resources, a special type of class called repository needs to be created. Katharsis will scan for these classes and, using annotations, it will discover the available methods.

For our Greeting resource we will create a GreetingRepositoryImpl which extends the ResourceRepositoryBase implementation of the ResourceRepositoryV2 repository interface. The ResourceRepositoryBase is a base class that takes care of some boiler-plate code like for example implementing findOne() with findAll(). Note that when extending the ResourceRepositoryBase only findAll() needs to be implemented to have a working read-only repository.

In this example, we will store the greeting resources in a simple HashMap and add a “Hello World!” greeting as a resource via the constructor.

Katharsis passes JSON API query parameters to repositories through a QuerySpec parameter. The implementation of the findAll() uses the apply() method which evaluates the querySpec against the provided list and returns the result. Note that the @Component annotation is needed so that Katharsis is able to find the repository.

package com.codenotfound.katharsis.domain.repository;

import java.util.HashMap;
import java.util.Map;

import org.springframework.stereotype.Component;

import com.codenotfound.katharsis.domain.model.Greeting;

import io.katharsis.queryspec.QuerySpec;
import io.katharsis.repository.ResourceRepositoryBase;
import io.katharsis.resource.list.ResourceList;

@Component
public class GreetingRepositoryImpl extends ResourceRepositoryBase<Greeting, Long> {

  private Map<Long, Greeting> greetings = new HashMap<>();

  public GreetingRepositoryImpl() {
    super(Greeting.class);

    greetings.put(1L, new Greeting(1L, "Hello World!"));
  }

  @Override
  public synchronized ResourceList<Greeting> findAll(QuerySpec querySpec) {
    return querySpec.apply(greetings.values());
  }
}

Setting Up the Server

Katharsis comes with out-of-the-box support for Spring Boot. The entry point is a KatharsisConfig class which configures Katharsis using Spring properties. Additionally, we have to make sure that each repository is annotated with @Component (as we did with the above GreetingRepositoryImpl).

Spring’s @RestController annotation is used to mark the KatharsisController class as a controller for handling HTTP requests. The KatharsisConfigV3 import will setup and expose the resource endpoints based on auto-scanning for specific annotations in addition to some properties which we will see further below.

Katharsis also ships with a ResourceRegistry which holds information on all the registered repositories. We expose this information on /resources-info by iterating over all the entries in the auto-wired ResourceRegistry.

package com.codenotfound.katharsis.server;

import java.util.HashMap;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Import;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.katharsis.resource.registry.RegistryEntry;
import io.katharsis.resource.registry.ResourceRegistry;
import io.katharsis.spring.boot.v3.KatharsisConfigV3;

@RestController
@Import({KatharsisConfigV3.class})
public class KatharsisController {

  @Autowired
  private ResourceRegistry resourceRegistry;

  @RequestMapping("/resources-info")
  public Map<String, String> getResources() {
    Map<String, String> result = new HashMap<>();
    // Add all resources
    for (RegistryEntry entry : resourceRegistry.getResources()) {
      result.put(entry.getResourceInformation().getResourceType(),
          resourceRegistry.getResourceUrl(entry.getResourceInformation()));
    }

    return result;
  }
}

In addition to the above auto-configuration, a number of items are configured using the application.yml properties file:

• The katharsis:resourcePackage property specifies which package(s) should be searched to find models and repositories used by the core and exception mappers. Multiple packages can be passed by specifying a comma separated string of packages.
• The katharsis:domainName property specifies the domain name as well as protocol and optionally port number to be used when building links objects in responses. The value must not end with a backslash (/).
• The katharsis:pathPrefix property defines the default prefix of the URL path used when building link objects in responses and when performing method matching.

katharsis:
  resourcePackage: com.codenotfound.katharsis.domain
  domainName: http://localhost:9090/codenotfound
  pathPrefix: /api

server:
  context-path: /codenotfound
  port: 9090

Setting Up the Client

Katharsis includes a Java client which allows communication with JSON-API compliant servers. To start using the client just create an instance of KatharsisClient and pass the service URL. Then use the client to create a repository that gives access to the different resource CRUD operations.

In the below GreetingClient we have created a findOne() method that returns a single Greeting based on the identifier.

package com.codenotfound.katharsis.client;

import javax.annotation.PostConstruct;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import com.codenotfound.katharsis.domain.model.Greeting;

import io.katharsis.client.KatharsisClient;
import io.katharsis.queryspec.QuerySpec;
import io.katharsis.repository.ResourceRepositoryV2;

@Component
public class GreetingClient {

  private static final Logger LOGGER = LoggerFactory.getLogger(GreetingClient.class);

  private KatharsisClient katharsisClient =
      new KatharsisClient("http://localhost:9090/codenotfound/api");
  private ResourceRepositoryV2<Greeting, Long> resourceRepositoryV2;

  @PostConstruct
  public void init() {
    resourceRepositoryV2 = katharsisClient.getRepositoryForType(Greeting.class);
  }

  public Greeting findOne(long id) {
    Greeting result = resourceRepositoryV2.findOne(id, new QuerySpec(Greeting.class));

    LOGGER.info("found {}", result.toString());
    return result;
  }
}

Testing the Hello World JSON API

Let’s test our greeting resource! If you are running Google Chrome you can simply do this from the browser. Make sure you start the application by starting up Spring Boot:

mvn spring-boot:run

Next, open the following URL which should show all our registered resources (in this example the greetings resource).

http://localhost:9090/codenotfound/resources-info

Go ahead and use the greetings endpoint as the next URL. This will show us all the available greetings.

http://localhost:9090/codenotfound/api/greetings

For the details of our Hello World resource, we enter the below URL.

http://localhost:9090/codenotfound/api/greetings/1

Notice that above flow is fully driven using hypermedia!

To wrap up we will also add a simple SpringKatharsisApplicationTest unit test case in which we lookup the Hello World greeting resource using it’s identifier.

package com.codenotfound.katharsis;

import static org.assertj.core.api.Assertions.assertThat;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.test.context.junit4.SpringRunner;

import com.codenotfound.katharsis.client.GreetingClient;

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.DEFINED_PORT)
public class SpringKatharsisApplicationTest {

  @Autowired
  GreetingClient greetingClient;

  @Test
  public void testFindOne() {
    assertThat(greetingClient.findOne(1L).getContent()).isEqualTo("Hello World!");
  }
}

Triggering the test case is done using the following Maven command.

mvn test

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v1.5.2.RELEASE)

09:35:41.763 [main] INFO  c.c.k.SpringKatharsisApplicationTest - Starting SpringKatharsisApplicationTest on cnf-pc with PID 1740 (started by CodeNotFound in c:\code\st\json-api\json-api-katharsis-helloworld)
09:35:41.765 [main] INFO  c.c.k.SpringKatharsisApplicationTest - No active profile set, falling back to default profiles: default
09:35:44.476 [main] INFO  c.c.k.SpringKatharsisApplicationTest - Started SpringKatharsisApplicationTest in 3.02 seconds (JVM running for 3.693)
09:35:44.900 [main] INFO  c.c.katharsis.client.GreetingClient - found com.codenotfound.katharsis.domain.model.Greeting@a52ca2e
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.574 sec - in com.codenotfound.katharsis.SpringKatharsisApplicationTest

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6.963 s
[INFO] Finished at: 2017-04-21T09:35:45+02:00
[INFO] Final Memory: 28M/262M
[INFO] ------------------------------------------------------------------------

If you would like to run the above code sample, you can get the full source code here.

This wraps up the Katharsis JSON API tutorial in which we developed a simple Hello World resource from scratch and exposed it via a RESTful API.