Java JSON API framework

Crnk 1.0: Crank up the development of RESTful applications

Remo Meier

© Shutterstock / Parvu

Crnk, a new open source project which allows developers to focus on what really matters —their applications, provides an end-to-end solution for RESTful application development that integrates well into the Java ecosystem. In this article, Remo Meier, senior software engineer at Adnovum Informatik AG gives us an overview of the Crnk framework and its benefits.

The design and implementation of RESTful applications can bring many challenges:

  • supporting CRUD operations.
  • a REST endpoint adhering to a standard to benefit from community support and a rich set of tooling.
  • providing an end-to-end solution from servers to browsers and mobile devices.
  • sorting, filtering and paging.
  • requesting and (atomically) modify complex object graphs.
  • linking of resources with HATEOAS and enriching data with meta-data.
  • mobile- friendliness by allowing to fetch object graphs in a single request and obtaining only the necessary parts of those objects with sparse field sets.
  • a meta-model for documentation and (UI) automation.
  • browsing of the API with a user-interface.
  • exception mapping for custom and default exception types.
  • integration with Java frameworks like Spring and JEE.

Crnk is a new open source project that aims to provide a solution to these and more challenges and lets developers focus on what matters instead: their applications. Crnk builds upon the JSON API standard for resource-based REST APIs. JSON API defines how a REST endpoint can look like. This includes basic features like CRUD, sorting, filtering and paging. But also more advanced patterns like querying resources and (possibly nested) related resources with a single request. On this basis, Crnk aims to provide an end-to-end solution for RESTful application development that integrates well into the Java ecosystem.

SEE ALSO: Spring Boot tutorial: REST services and microservices

Framework agnostic and modular

The core of Crnk is small in size and integrates with most Java frameworks such as Spring, Servlet API, CDI, Dropwizard and JAX-RS. There is a rich and growing set of modules that extend the feature set of Crnk. A JPA module exposes entities as REST endpoint with all the benefits that come with JSON API. Advanced customization options can map those entities to DTOs or secure the entities on a table, row or column level. In contrast, a Brave module brings support for tracing with Zipkin. Other modules can be found on the Crnk web page. The documentation further shows how custom modules can be implemented.

Example

The JSON API specification makes use of resources and repositories. A resource written with Crnk can look as simple as:

@JsonApiResource(type = "schedules")
public class Schedule {
	@JsonApiId
	private Long id;
	private String name;
         …
}

and for a repository:

@ApplicationScoped
public class ScheduleRepositoryImpl extends ResourceRepositoryBase<Schedule, Long>{

	private Map<Long, Schedule> schedules = new HashMap<>();

	@Override
	public ResourceList<Schedule> findAll(QuerySpec querySpec) {
		return querySpec.apply(schedules.values());
	}

	@Override
	public <S extends Schedule> S save(S entity) {
		schedules.put(entity.getId(), entity);
		return null;
	}

	@Override
	public void delete(Long id) {
		schedules.remove(id);
	}
}

The example makes use of in-memory sorting, filtering and paging. It supports request URLs such as:

  • http://127.0.0.1:8080/schedule
  • http://127.0.0.1:8080/schedule
  • http://127.0.0.1:8080/schedule/myScheduleId
  • http://127.0.0.1:8080/schedule?filter[name][GT]=scheduleName1&page[limit]=3&sort=-name

More advanced use cases may map that QuerySpec parameter to a native query of the data store in use.

Type-safe and testable

Crnk comes with support for client applications. Many parts of the API are accessible from both server and client side. There is a Crnk client that creates type-safe stubs out of repository interfaces; which in turn can be used by Java and Android devices.

Testing benefits from the fact that JSON API standardizes the REST layer. As such there is less of a need for low-level REST testing with tools like REST-assured. Instead, the application can focus on their application logic and tests can look like:

@Override
public void test(){
  CrnkClient client = new CrnkClient(http://...);
  ResourceRepositoryV2<Task> repository = client.getRepositoryForType(Task.class);
  ResourceList<Task> tasks = repository.findAll(new QuerySpec(Task.class));
  Assert.assertEquals(…); 
}

The generation of Typescript interfaces is supported with a Gradle plugin. It brings type-safe development to web and hybrid mobile applications. The generator currently targets Angular application making use of the redux pattern with ngrx; a combination that is gaining more and more popularity. The normalized structure of a JSON API document fits in here quite naturally and can easily be put into a redux store.

SEE ALSO: Microservices and DevOps accelerate API-first movement

Meta model

Crnk comes with a rich meta model similar to the Java reflections API. It makes the internal workings of Crnk accessible as JSON API repositories. For example, it allows to query:

  • available repositories
  • attributes of resources
  • type information
  • nullability

The API can be used, for example, for documentation and UI automation purposes.

Conclusion

The JSON API specification provides a solid basis for Crnk. Integrations into many Java frameworks complement JSON API and facilitate the adoption by Java applications. But there is much more to tell.

Information about features, documentation and a roadmap can be found here.

Author

Remo Meier

Remo Meier obtained a PhD in computer science from the ETH in Zurich. He works as a senior software engineer at Adnovum Informatik AG with a background in enterprise Java.  His main technical interests are software architecture, security and standardization resp. automation in Enterprise software landscapes.


Comments
comments powered by Disqus