Crnk Documentation

Crnk library requires minimum Java 8 (as of Crnk 2.4) to build and run. In the future it will come with support for both the current major Java releases (9, 10, 11, etc.) and the current long-term support version that gets released every three years.

Crnk Maven artifacts are available from Bintray/JCenter.

https://bintray.com/crnk-project

In Gradle it looks like:

Note that due to performance/reliability issues, releases are only intermittently pushed to Maven Central. It is highly recommended for project to go with JCenter as well.

Stable releases hosted on Bintray/JCenter are also available from:

https://bintray.com/crnk-project/maven https://dl.bintray.com/crnk-project/maven/

Most recent builds are available from (for a limited period of time):

https://bintray.com/crnk-project/mavenLatest https://dl.bintray.com/crnk-project/mavenLatest/

With io.crnk:crnk-bom a Maven BOM is provided that manages the dependencies of all crnk artifacts. In Gradle the setup then looks as follows:

The crnk modules can then simply be used without having to specify a version:

Crnk makes use of SLF4J to do logging. Make sure to have the API properly setup. For example by making use of Logback or one of the many bridges to other Logging frameworks.

Crnk allows integration with JAX-RS environments through the usage of JAX-RS specification. JAX-RS 2.0 is required for this integration. Under the hood there is a @PreMatching filter which checks each request for JSON API processing. The setup can look as simple as:

There are two ways of integrating crnk using Servlets:

Crnk provides with:

There is a CrnkCoreAutoConfiguration in crnk-setup-spring-boot2 that outlines the basic setup that can easily be applied to a Spring-only setup without Spring Boot using crnk-setup-spring:

There are further auto configurations that automatically setup various Crnk modules. And there are also further integrations into Spring (like for RestTemplate and Spring Security). More information is available in Spring modules.

The web integration can be customized for Spring Boot setups with the subsequent properties:

See CrnkCoreProperties for more information. The Spring modules and their auto configurations make further configuration properties available.

Crnk integrates with Vert.x RxJava 2 using crnk-reactive and crnk-setup-vertx. More information about reactive programming is available here. To make use of Crnk with Vert.x, make sure you have the following dependencies specified:

An example Vert.x vehicle may then look like:

CrnkVertxHandler holds the Crnk setup. Its constructor takes a Consumer<CrnkBoot> that allows the customization of Crnk. The example makes use of it to register two modules. CrnkVertxHandler.process is the main method that allows to process HttpServerRequest objects of Vert.x.

To enable CDI support, add io.crnk:crnk-cdi to your classpath. Crnk will then pickup the CdiServiceDiscovery implementation and use it to discover its modules and repositories. Modules, repositories, etc. will then be picked up if they are registered as CDI beans.

By default Cdi.current() is used to obtain a BeanManager. The application may also make use of CdiServiceDiscovery.setBeanManager(…​) to set a custom one. The various integrations like CrnkFeature provide a setServiceDiscovery method to set a customized instance.

A GuiceServiceDiscovery implementation is provided. The various integrations like CrnkFeature provide a setServiceDiscovery method to set the instance. For an example have a look at the dropwizard example application (https://github.com/crnk-project/crnk-framework/tree/master/crnk-integration-examples/dropwizard-simple-example).

The Spring integration comes with a SpringServiceDiscovery that makes use of the Spring ApplicationContext to discover beans.

If no dependency injection framework is used, Crnk can also discover beans on its own. For this purpose, the org.reflections:reflections library has to be added to the classpath and the CrnkProperties.RESOURCE_SEARCH_PACKAGE be defined. In JAX-RS this may look like:

A JsonServiceLocator service locator can be provided to control the instatiation of object. By default the default constructor will be used. The CrnkProperties.RESOURCE_SEARCH_PACKAGE property is passed to define which package should be searched for beans. Multiple packages can be passed by specifying a comma separated string of packages i.e. com.company.service.dto,com.company.service.repository. It will pick up any public non-abstract class that makes use of Crnk interfaces, like repositories, exception mappers and modules.

It is also possible to make use of no discovery mechanism at all. In this case it is still possible to add repositories and other features through modules. A simple example looks like:

Have a look at the various [modules] chapters for more information.

Application can bring along there own implementation of ServiceDiscovery. For more information see here.

CrnkBoot is a class shared among all the different integrations that takes care of setting up and starting Crnk. Every integration will provide access to it:

CrnkBoot allows for virtually any kind of customization not directly provided by the integration itself, such as Spring Boot auto configurations and properties. Some possibilities:

Any of the integrations allows API access to customize Crnk. There are also a number of configuration flags provided by CrnkProperties:

It is the most important annotation which defines a resource. It requires type parameter to be defined that is used to form a URLs and type field in passed JSONs. According to JSON API standard, the name defined in type can be either plural or singular

The example below shows a sample class which contains a definition of a resource.

where type parameter specifies the resource’s name.

By default the type of a resource in a JSON API document and its name within URLs match, for example:

The optional resourcePath allows to define separate values, typically with resourcePath being plural and type being singular:

resulting in (notice the self link does not change, but type does):

The optional pagingSpec parameter allows to set the desired paging specification:

There is built-in support for OffsetLimitPagingSpec (default) or NumberSizePagingSpec. The paging spec must be backed by a matching PagingBehavior implementation. More detailed information about pagination can be found at Pagination section.

Defines a field which will be used as an identifier of a resource. Each resource requires this annotation to be present on a field which type implements Serializable or is of primitive type.

The example below shows a sample class which contains a definition of a field which contains an identifier.

Indicates an association to either a single value or collection of resources. The type of such fields must be a valid resource.

The example below shows a sample class which contains this kind of relationship.

The optional serialize parameter specifies how the association should be serialized when making a request. There are two things to consider. Whether related resources should be added to the include section of the response document. And whether the id of related resources should be serialized along with the resource in the corresponding relationships.[name].data section. Either LAZY, ONLY_ID or EAGER can be specified:

There are two possibilities of how related resources are fetched. Either the requested repository directly returns related resources with the returned resources. Or Crnk can take-over that work by doing nested calls to the corresponding RelationshipRepositoryV2 implementations. The behavior is controlled by the optional lookUp parameter. There are three options:

There are many different ways how a relationship may end-up being implemented. In the best case, no implementation is necessary at all and requests can be dispatches to one of the two related resource repositories. The repositoryBehavior allows to configure behavior:

The forwarding behaviors are implemented by ForwardingRelationshipRepository.

Fields annotated with @JsonApiRelation hold fully-realized related resources. There are situations where the id of a related resource is available for free or can be obtained much more cheaply then fetching the entire related resource. In this case resources can make use of fields annotated with @JsonApiRelationId. The complement @JsonApiRelation fields by holding there ID only. An example looks like:

Notice that: - Schedule resource holds both a project and projectId field that point to the same related resource. - setters must set both properties to make sure they stay in sync. If only the ID is set, the object must be nulled. - propertyId will never show in requests and responses. It can be considered to be transient.

By default, the naming convention for @JsonApiRelationId field is to end with a Id or Ids suffix. Crnk will the pair those two objects automatically. Trailing s are ignored for multi-valued fields, meaning that projectIds matches with projects. But it is also possible to specify a custom name, for example:

If a @JsonApiRelationId field cannot be matched to a @JsonApiRelation field, an exception will be thrown.

@JsonApiRelationId fields are used for:

Further (substantial) benefit for @JsonApiRelationId fields is that no RelationshipRepository must be implemented. Instead Crnk will automatically dispatch relationship requests to the owning and opposite ResourceRepository. This allows to focus on the development of ResourceRepository. See RelationshipRepository for more information.

Field or getter annotated with JsonApiMetaInformation are marked to carry a MetaInformation implementation. See http://jsonapi.org/format/#document-meta for more information about meta data. Example:

Field or getter annotated with JsonApiLinksInformation are marked to carry a LinksInformation implementation. See http://jsonapi.org/format/#document-links for more information about linking. Example:

By default links are serialized as:

With crnk.config.serialize.object.links=true links get serialized as:

Crnk comes with (partial) support for Jackson annotations. Currently supported are:

Support for more annotations will be added in the future. PRs welcomed.

ResourceRepositoryV2 is the main interface used to operate on resources with POST, GET, PATCH and DELETE requests. The interface takes two generic arguments:

The methods of ResourceRepositoryV2 look as follows:

The ResourceRepositoryBase is a base class that takes care of some boiler-plate, like implementing findOne with findAll. An implementation can then look as simple as:

and

The example is taken from crnk-examples/spring-boot-example. (the basic Spring boot example from crnk-framework, not the dedicated full-blown one from crnk-example).

Together with matching project repository, some URLs to checkout:

You may notice that:

This is one small example that shows the power of native resource-oriented REST libraries. Implementing a similar API with more classical REST libraries can be a substantial amount of work.

There is further a ReadOnlyResourceRepositoryBase base class that does not allow to override the create, delete and update methods. crnk-meta accordingly reports insertable, updateable, deltable for such repositories as false.

Crnk passes JSON API query parameters to repositories trough a QuerySpec parameter. It holds request parameters like sorting and filtering specified by JSON API. The subsequent sections will provide a number of example.

For example showing its use URLs also have a look at the ResourceRepositoryV2 section.

Each relationship defined in Crnk (annotation @JsonApiRelation) must have a relationship repository defined implementing RelationshipRepositoryV2. RelationshipRepositoryV2 implements the methods necessary to work with a relationship. It provides methods for both single-valued and multi-valued relationships:

All of the methods in this interface have fieldName field as their last parameter in case there are multiple relationships between two resources.

ResourceRepositoryV2 and RelationshipRepositoryV2 return lists of type ResourceList. The ResourceList can carry, next to the actual resources, also meta and links information:

There is a default implementation named DefaultResourceList. To gain type-safety, improved readability and crnk-client support, application may provide a custom implementation extending ResourceListBase:

This implementation can then be added to a repository interface declaration and used by both servers and clients:

Processing errors in Crnk can be handled by throwing an exception and providing a corresponding exception mapper which defines mapping to a proper JSON API error response.

There is a special interface which can be added to resource repositories to provide meta information: io.crnk.core.repository.MetaRepository. It contains a single method MetaInformation getMetaInformation(Iterable<T> resources) which return meta information object that implements the marker interface io.crnk.response.MetaInformation.

If you want to add meta information along with the responses, all repositories (those that implement ResourceRepository and RelationshipRepository) must implement MetaRepository.

When using annotated versions of repositories, a method that returns a MetaInformation object should be annotated with JsonApiMeta and the first parameter of the method must be a list of resources.

There is a special interface which can be added to resource repositories to provide links information: io.crnk.core.repository.LinksRepository. It contains a single method LinksInformation getLinksInformation(Iterable<T> resources) which return links information object that implements the marker interface io.crnk.response.LinksInformation.

If you want to add meta information along with the responses, all repositories (those that implement ResourceRepository and RelationshipRepository), must implement LinksRepository.

When using annotated versions of repositories, a method that returns a LinksInformation object should be annotated with JsonApiLinks and the first parameter of the method has to be a list of resources.

Self and related links can make up to 60% of the response payload size and not always are those links of use. Crnk offers a Crnk-Compact: true header that can be sent along with the request. In this case the computation of those links is omitted. Further relationships without data are completely omitted.

Sometimes it is useful to augment a repository with further features. There are different situations where that can makes sense:

RepositoryDecoratorFactory allows to do exactly that. It puts a decorating resource or relationship repository inbetween the Crnk engine and the main repository. It implements the same interface contract as the main repository, intercept all requests and can do arbitrary modifications. The modifications may or may not include calling the main repository.

An example can look like:

The particular example, for example, intercepts the save operation and may trigger an approval workflow:

The ResourceFieldContributor interface allows to dynamically introduce new fields to resources without actually touching them. This is useful, for example, if you have a JPA entity exposed with crnk-jpa and want to add further fields like that mentioned history relationship from the earlier relationship example. ResourceFieldContributor can be implemented by a repository or obtained from the regular service discovery mechanism.

Any type of field can be added: meta, links, attribute and relationship fields. For relationship fields an application may make use of RelationshipMatcher to provide repository serving those fields. Notice the accessor property that is used to obtain the value of that field (make sure this method is efficient to execute). An example is given by the HistoryRelationshipRepository in crnk-examples/spring-boot-example:

The basic setup is as simple as:

Three underlying http client libraries are supported:

Add one of those library to the classpath and Crnk will pick it up automatically. A custom HttpAdapter can also set passed to CrnkClient.setHttpAdapter(…​).

or

The client has three main methods:

The interface of the repositories is as same as defined in `Repositories`_ section.

An example of the usage:

Have a look at, for example, the QuerySpecClientTest to see more examples of how it is used.

Crnk clienet and server share the URL handling. QuerySpecUrlMapper performs the mapping of HTTP request parameters to QuerySpec. For more information see url mapping.

CrnkClient can be extended by modules:

Typical use cases include:

Many modules allow a registration both on server and client side. The client part then typically makes use of a subset of the server features, like exception mappers and resource registrations.

There is a mechanism to discover and register client modules automatically:

findModules makes use of java.util.ServiceLoader and looks up for ClientModuleFactory. JpaModule, ValidationModule, MetaModule, SecurityModule implement such a service registration. In contrast, BraveModule needs a Brave instance and does not yet allow a fully automated setup.

It is possible to work with CrnkClient in a fully type-safe manner.

In a first step an interface for a repository is defined:

And then it can be used like:

The interface stubs from the previous section can also be used to make calls to JAX-RS. For example, the ScheduleRepository can be complemented with a JAX-RS annotation:

and further JAX-RS services can be added:

To make this work a dependency to org.glassfish.jersey.ext:jersey-proxy-client must be added and JerseyActionStubFactory registered with CrnkClient:

Then a client can make use the Crnk stubs and it will transparently switch between JSON-API and JAX-RS calls:

It is possible to hook into the HTTP implementation used by Crnk ( or Apache). Make use of CrnkClient#getHttpAdapter() and cast it to either HttpAdapter. Both implementations provide a addListener method, which in turn gives access to the native builder used to construct the respective HTTP client implementation. This allows to cover various use cases:

Some examples:

The subsequent example shows as simple reactive resource repository holding its data in-memory:

The following snipped shows how to setup the ReactiveModule together with AsyncCrnkServlet in Spring:

Ready-to-use integrations into Spring, Vert.x and Ratpack are planned for the near future.

Reactive and traditional repositories work well together side-by-side and can also be used in a mixed setting, for example when requesting the inclusion of related resources. Since the traditional repositories will block the caller, there are two mechanisms in place to remedy the issue:

Contributions in any area welcomed. :basedir: ../../../..

Authorization requires to first know the calling user through authentication. Crnk is agnostic to the used authorization scheme and is usually provided by the underlying integration, for example, the Principal of JEE or the SecurityContext of Spring Security. They in turn are populated from a scheme like OAuth, JWT or SAML.

Crnk makes use of SecurityProvider to integrate with such systems and check access to roles for the current user:

The JAX-RS and servlet integration of Crnk come both with a SecurityProvider implementation. Which in turn also provides an implementation for all integrations derived from them, such as Spring.

The SecurityProvider is accessible from the module API and can be used to perform both DAC and RBAC or any other kind of check.

There is a SecurityModule provided by crnk-security that intercepts all repository requests and perform access control. Currently it supports resource-based access control. A setup can looks as follows:

A builder is used to construct rules. Each rule grants access to either a given or all resources. Thereby ResourcePermission specifies the set of authorized methods: GET, POST, PATCH, DELETE.

Once the rules are defined, the runtime checks go well beyond more traditional approaches like JEE @RolesAllowed annotation. The rules are enforced in various contexts:

Internally the security module makes use of ResourceFilter to perform this task. More information about that is available in a subsequent section.

Is is up to the application how and when to configure the SecurityModule. The set of rules can be static or created dynamically. SecurityModule.reconfigure(…​) allows to replace the security rules at runtime.

The SecurityModule is only one example how to implement security. Underlying it is the ResourceFilter interface provided by the Crnk engine:

ResourceFilter allows to restrict access to resources and fields. To methods filterResource and filterField can be implemented for this purpose. Both return a FilterBehavior which allows to distinguish between NONE, IGNORE and FORBIDDEN. For example, a field like a lock count can make use of IGNORE in order to be ignored for POST and PATCH requests (the current value on the server is left untouched). While access to an unauthorized resource or field results in a forbidden error with FORBIDDEN. An example is given by the SecurityResourceFilter of SecurityModule in 'crnk-security`. Since ResourceFilter methods are invoked often, it is important for them to return quickly.

There is a ResourceFilterDirectory that complements ResourceFilter. It allows to query the authorization status of a particular resource or field in context of the current request. The ResourceFilterDirectory makes use of per-request caching as the information may be accessed repeatedly for a request. It can be obtained with ModuleContext.getResourceFilterDirectory(…​) from the module API. For example, the MetaModule and HomeModule make use of ResourceFilterDirectory to only list authorized elements.

Filtering of resources is one of the main building blocks of JSON API. As such it is typically not too hard to implement DAC. The roles of a user can be checked and if necessary for filters specific to that user can be added. There are two possibilities to add such filters:

In the future the SecurityModule may be enhanced to also support DAC.

In many cases it is desired to adjust UIs based on the authorizations of a user to guide the user early what he is authorized to do. There are two mechanisms that are outlined in the next sections.

A frequent use case is to display user/login related information for a user. However, Crnk does not do authentication on its own and the set of provided information is typically application-specific. As such there is no direct support from Crnk, but a custom repository can look like:

This particular example has been taken from crnk-example.

Crnk comes with four exceptions that are relevant in a security context:

The JPA module allows to automatically expose JPA entities as JSON API repositories. No implementation or Crnk-specific annotations are necessary.

The feature set includes:

Have a look at the Spring Boot example application which makes use of the JPA module, DTO mapping and computed attributes.

Not yet supported are sparse field sets queried by tuple queries.

A ValidationModule provided by io.crnk:crnk-validation implements resource validation and provides exception mappers for javax.validation.ValidationException and javax.validation.ConstraintViolationException. Among others, it properly translates 'javax.validation.ConstraintViolation' instances to JSON API errors. A JSON API error can, among others, contain a source pointer. This source pointer allows a clients/UI to display the validation errors next to the corresponding input fields.

A translated exception can look like:

Notice the 422 status code used for such errors.

As mentioned above, resource validation mechanism enabled by default will be applied in case of one of the following request types: POST, PUT and PATCH. Once described behavior is unwanted, module should be defined in the following way:

A BraveClientModule and BraveServletModule provided by io.crnk:crnk-monitor-brave4 provides integration into Zipkin/Brave to implement tracing for your repositories. The module is applicable to both a Crnk client or server.

The Crnk client can make use of either HttpClient or OkHttp to issue HTTP requests. Accordingly, a matching brave integration must be added to the classpath:

The BraveClientModule then takes care of the integration and will create a client span for each request.

On the server-side, BraveServletModule creates a local span for each accessed repository. Every request triggers one or more repository accesses (depending on whether relations are included). Note however that BraveServletModule does not setup tracing for incoming requests. That is the purpose of the JAX-RS/servlet integration of Brave.

Have a look at the Spring boot example application to see the BraveServletModule in use together with a log reporter writing the output to console.

This is a module that exposes the internal workings of Crnk as JSON API repositories. It lets you browse the set of available resources, their types, their attributes, etc. For example, Crnk UI make use of the meta module to implement auto-completing of input fields.

The HomeModule provides a listing of available resources in each directory (such as the root /api/). Note that directory paths always end with a '/' and the HomeModule will process the request if there is no resource or relationship repository serving that particular path.

The HomeModule supports two kinds of formats that can be choosen upon creation. A JSON API-style format where a links node holds all links to child directories and repositories. And a JSON HOME format as specified by JSON Home.

In the Spring Boot example applications it looks like:

Notice the meta entry with a trailing '/' that allows to move to subdirectory http://localhost:8080/api/meta/:

By its nature RESTful applications are limited to the insertion, update and deletion of single resources. As such, developers have to design resources accordingly while having to consider aspects like transaction handling and atomicity. It is not uncommon to combine multiple data objects on the server-side and expose it as single resource to clients. It is a simple approach, but can also mean quite a substantial overhead when having to implement potentially redudant repositories. Furthermore, things like validation handling, relationships and supporting complex object graphs can get tricky when a single resource starts holding complex object graphs again.

For all the before mentioned reason support for jsonpatch.com is provided. It allows to send multiple insertions, updates and deletions with a single request and provides the results for each such executed operation. Note that numerous attempts and discussions have taken place and are still ongoing to establish a common JSON API standard, but that does not seem to make much progress. With jsonpatch.com there is already an estabilished standard that fits well for many use cases.

The implementation is provided as OperationsModule and the setup looks like:

Further filters can be applied to intercept incoming requests. Typically applications will make use of that to start a new transaction spanning all requests. This looks as follows:

There is further an operations client implementation that works along the regular JSON API client implementation:

An example request in JSON looks like:

and an example response JSON looks as follows:

Notice in the response a status code for each request. It is import for the Content-Type and Accept HTTP headers to have application/json-patch+json, otherwise the OperationsModule will ignore such requests.

The current limitations of the implementation are:

With support for POST, PATCH and DELETE operations the most important building blocks should be in place. The limitations are expected to be addressed at some point as well, contributions welcomed.

The UI module makes crnk-ui accessible trough the module system. It allows to browse and edit all the repositories and resources. The setup looks like:

By default the user interface is accessible from the /browse/ directory next to all the repositories. Have a look at the Spring Boot example application to see a working example.

This module is currently in incubation. Please provide feedback.

An example from the Spring Boot example application looks like:

There is an ActivitiModule for the Activiti workflow engine that offers an alternative REST API. The motivation of ActivitiModule is to:

This setup differs substantially from the API provided by Activiti that is implemented in generic fashion.

All Spring modules are hosted in the crnk-spring modules without explicit runtime-time dependency. Each module comes with an auto configuration that is enabled if the presence of the particular Spring component is detected. Each module comes with an enabled property to disable the auto configuration.

Crnk provides three different, complementing mechanisms to hook into the request processing.

The DocumentFilter interface allows to intercept incoming requests and do any kind of validation, changes, monitoring, transaction handling, etc. DocumentFilter can be hooked into Crnk by setting up a module and registering the filter to the ModuleContext. Not that for every request, this interface is called exactly once.

A request may span multiple repository accesses. To intercept the actual repository requests, implement the RepositoryFilter interface. RepositoryFilter has a number of methods that allow two intercept the repository request at different stages. Like Filter it can be hooked into Crnk by setting up a module and registering the filter to the ModuleContext.

Similar to RepositoryFilter it is possible to decorate a repository with another repository implementing the same Crnk repository interfaces. The decorated repository instead of the actual repository will get called and it is up to the decorated repository of how to proceed with the request, usually by calling the actual repository. RepositoryDecoratorFactory can be registered with ModuleContext.addRepositoryDecoratorFactory. The factory gets notified about every repository registration and is then free do decorate it or not.

ResourceFilter allows to restrict access to resources and fields. To methods filterResource and filterField can be implemented for this purpose. Both return a FilterBehavior which allows to distinguish between NONE, IGNORE and FORBIDDEN. For example, a field like a lock count can make use of IGNORE in order to be ignored for POST and PATCH requests (the current value on the server is left untouched). While access to an unauthorized resource or field results in a forbidden error with FORBIDDEN.

The SecurityModule makes use of ResourceFilter to perform access control. SecurityResourceFilter in 'crnk-security` gives an example how it is used. The MetaModule and HomeModule make use of ResourceFilterDirectory obtained with ModuleContext.getResourceFilterDirectory(…​) to query those ResourceFilter and only display information about resources and fields accessible in the context of the current re quest. The ResourceFilterDirectory makes use of per-request caching as the information may be accessed repeatedly for a request.

Changes to attributes and relationships can be tracked by implementing ResourceModificationFilter. The filter is invoked upon an incoming request while setting up the resource objects; before the actual repository is called. Such filters are useful, for example, to implement auditing functionality.

DocumentFilter, RepositoryFilter and ResourceModificationFilter can implement Prioritizable to introduce a priority among multiple filters.

HttpRequestContext resp. HttpRequestContextProvider provides access to the HTTP requests. Most notably to get and set HTTP request and response headers. In many cases, the underlying implementation like JAXRS or Servlet provides that access as well. With HttpRequestContext there is an implementation that is independent of that implementation. As such it is well suited for module development, in particular for request filtering. A typical use case is to set and access security headers.

HttpRequestContextProvider.getRequestContext returns the request context for the currently active request. Modules have access to HttpRequestContextProvider trough the ModuleContext. Repositories, filters and modules can implement HttpRequestContextAware to get access to HttpRequestContextProvider.

ModuleExtension is an interface can can be implemented by modules to specify a contract how others can extend it. The interface has two mandator properties: targetModule and optional. targetModule specifies the module consuming those extensions (and providing the implementation for it). optional specifies whether the target module must be registered or not. In case of an optional extension without the module being registered, the extension is simply ignored. The implementing module is free to add any further, custom methods to provide extension hooks to other modules. To get access to this extensions, the module can implement ModuleExtensionAware. Extensions must be registered during Module.setupModule(…​) and will be available to the target module when Module.init() is called.

For an example have a look at MetaModuleExtension and the JpaModule making use of it. The ModuleExtension was introduced with Crnk 2.0 and its use is expected to grow heavily over time.

The core of Crnk is quite flexible when it comes to implementing repositories. As such, it is not mandatory to make use of the Crnk annotations and conventions. Instead, it is also (likely) possible to integrate an existing data store setup like JPA, JDBC, ElasticSearch, etc. into Crnk. For this purpose a module can provide custom implementations of ResourceInformationBuilder and RepositoryInformationBuilder trough ModuleContext.addResourceInformationBuilder and ModuleContext.addRepositoryInformationBuilder. For example, the JpaModule of crnk-jpa makes use of that to read JPA instead of Crnk annotations. Such a module can then register additional (usually dynamic) repositories with ModuleContext.addRepository.

Crnk comes with out-of-the-box support for Spring and CDI. Both of them implement ServiceDiscovery. You may provide your own implementation which can be hooked into the various Crnk integrations, like the CrnkFeature. Alternatively, it can be auto-detected through the Java service mechanism. For example, crnk-cdi makes use of:

Modules have access to that ServiceDiscovery trough the ModuleContext.getServiceDiscovery().

Modules for the Crnk client can additionally implement HttpAdapterAware. It gives the module access to the underlying HTTP client implementation and allows arbitrary customizations of it. Have a look at the Crnk client documentation for more information.

Adding a new integration has become quite simple in recent times. Have a look at crnk-servlet and crnk-rs. Most functionality necessary is already be provided by crnk-core. The steps include:

Repositories are usually created at compile-time, either by making use of the various annotations or a module such as the ´JpaModule´. However, the module API also allows the creation of repositories at runtime. There are two complementary mechanisms in place to achieve this and outlined in the next two sections.

If a module does not need configuration, it can provide a ClientModuleFactory implementation and register it to the java.util.ServiceLoader by adding a 'META-INF/services/io.crnk.client.module.ClientModuleFactory` file with the implementation class name. This lets CrnkClient discover the module automatically when calling CrnkClient.findModules(). An example looks like:

and

The Typescript generator allows the generation of:

Currently the generator targets the ngrx-json-api library. Support for other libraries/formats would be straightforward to add, contributions welcomed. A generated resource looks like:

For an example have a look at the Crnk example application, see crnk-project/crnk-example.

@crnk/angular-ngrx provides a number of different components:

All of those components are fairly lightweight and can also be used independently (if not specified otherwise above).

CrnkOperationsModule imported from @crnk/angular-ngrx/operations provides client side support for JSON PATCH. This enables clients to issue bulk requests. See Operations module for more information about how it is implemented in Crnk.

CrnkOperationsModule integrates into NgrxJsonApiModule by replacing the implementation of ApiApplyInitAction in ngrx-json-api. Instead of issuing multiple requests, it will then issue a single bulk JSON Patch request. The bulk response triggers the usual ApiApplySuccessAction resp. ApiApplyFailAction.

Have a look at crnk.operations.effects.spec.ts for a test case demonstrating its use.

@crnk/angular-ngrx/expression provides a QueryDSL-like expression model for Typescript. It is used to address boiler-plate when working with the Angular FormModule resp. ngModel directly. For example, when an input field needs to be bound to a JSON API resource field, a number of things must happen:

ngModel is limited to holding a simple value. In contrast, the use cases here require an understanding of the entire resource. It is necessary to have full JSON API resource and the path to the field to determine the field value and errors. This is achieved with @crnk/angular-ngrx/expression:

Such expressions and paths can be constructed manually. Or, in most cases, crnk-gen-typescript can take care of that. In this case usage looks like:

Note that:

The CrnkBindingFormModule provides two directives crnkExpression and crnkFormExpression that represent the ngModel counter-parts for expressions. While the former can be used standalone, the later is used for forms and registers itself to ngForm with the name provided by toFormName. Usage can look like:

or

Notice the required validation directive. crnkExpression and crnkFormExpression support validation and ControlValueAccessor exactly like ngModel.

The use of expressions provides an (optional) foundation for the form and table binding discussed in the next sections.

Working with forms and JSON API is the same for many use cases:

The FormBinding class provided by CrnkExpressionFormModule can take care of exactly this.

Similar to FormBinding there is a DataTableBinding class. It can help taking care of interfacing a table component with JSON API.

@crnk/angular-ngrx/meta hosts a Typescript API for Meta Module generated by crnk-gen-typescript.