Crnk Framework

The @crnk/angular-ngrx package provides several specialized modules to integrate Angular components with ngrx-json-api and JSON:API resources:

• @crnk/angular-ngrx/operations: Implements JSON PATCH support via CrnkOperationsModule, enabling bulk insert, update, and delete capabilities by replacing standard ApiApplyInitAction implementations with single bulk requests.
• @crnk/angular-ngrx/expression: Provides a type-safe, QueryDSL-like expression model for TypeScript to address the boilerplate of binding JSON:API resource fields to Angular components.
• @crnk/angular-ngrx/expression/forms: Binds the expression model to Angular form components (a JSON:API specific flavor of ngModel).
• @crnk/angular-ngrx/binding: Contains helper classes like FormBinding and DataTableBinding to connect tables and forms to JSON:API resources.
• @crnk/angular-ngrx/meta: Provides the TypeScript API for the Meta Module generated by crnk-gen-typescript.
• @crnk/angular-ngrx/stub: Contains minor base classes used by the TypeScript generator.

Crnk is a native resource-oriented REST library designed to accelerate the development of RESTful applications. Unlike traditional REST libraries, Crnk focuses on resources, their relationships, and repositories as the primary building blocks. This approach allows developers to focus on application logic rather than low-level protocol details.

Key capabilities include:

• Standardized URL handling: Supports patterns like /api/persons?filter[title]=John and /api/persons/{id}.
• Advanced Querying: Built-in support for sorting, filtering, pagination, and sparse field sets (partial objects).
• Complex Data Graphs: Supports requesting complex object graphs in a single request using JSON:API inclusions.
• Resource Operations: Supports inserting, updating, deleting, and atomic operations via jsonpatch.com.
• Metadata & Links: Ability to attach link and meta information to resources.
• Extensibility: A flexible module API to choose and extend features, along with filters and decorators to intercept and modify application aspects.

The @crnk/angular-ngrx/expression module solves the problem of binding Angular components to complex JSON:API resources. While ngModel only handles simple values, Crnk Expressions allow components to understand the full resource and the specific path to a field, which is necessary for proper validation and error mapping.

Key abstractions:

• Expression: An interface representing any value obtainable from a resource.
• Path<T>: Implements Expression and refers to a property of type <T> in an object.
• BeanBinding: Implements Path and represents the root resource (an empty path).
• Type-safe implementations like StringPath, NumberPath, BooleanPath, and BeanPath<T> are used to handle primitives and objects.

Commonly used methods on expressions:

• getValue(): Fetches the value at the given path.
• setValue(): Sets the value at the given path.
• toFormName(): Computes a unique form name (composed of resource type, ID, and path) to allow multiple resources to be edited on one screen.
• toQueryPath(): Constructs a path for sorting/filtering that excludes JSON:API structural elements like attributes or relationships.

<!-- Standalone expression binding -->
<input id="nameInput" [crnkExpression="resource.attributes.name"/>

<!-- Form binding (registers with ngForm using toFormName) -->
<input id="nameInput" required [crnkFormExpression="resource.attributes.name"/>

Crnk passes JSON:API query parameters to repositories via a QuerySpec object. This object encapsulates request parameters like sorting, filtering, and paging.

Common Spec classes used within QuerySpec:

• FilterSpec: Represents attribute paths, operators, and values.
• SortSpec: Represents sorting directions and paths.
• PagingSpec: Represents offset/limit or number/size paging.
• IncludeFieldSpec: Represents requested field sets.
• IncludeRelationSpec: Represents requested resource inclusions.

QuerySpec also provides an apply(Iterable<T> resources) method, which allows for in-memory sorting, filtering, and paging on any java.util.Collection. This is highly useful for testing or working with small datasets.

public class QuerySpec {
	public <T> List<T> apply(Iterable<T> resources){...}
	public Long getLimit() {...}
	public long getOffset() {...}
	public PagingSpec getPagingSpec() {...}
	public List<FilterSpec> getFilters() {...}
	public List<SortSpec> getSort() {...}
	public List<IncludeFieldSpec> getIncludedFields() {...}
	public List<IncludeRelationSpec> getIncludedRelations() {...}
	public QuerySpec getQuerySpec(Class<?> resourceClass) {...}
	...
}

While Crnk follows the JSON:API specification by default, you can use a simpler, non-JSON:API format via the crnk-format-plain-json module. This module provides the PlainJsonFormatModule, which allows for a flatter resource structure by removing the attributes and relationships containers and inlining relationships directly within the resource.

The PlainJsonFormatModule can be applied to both CrnkBoot (server-side) and CrnkClient (client-side). The format is selected using the HTTP Accept and Content-Type headers, meaning the standard JSON:API endpoint remains functional and accessible.

{
  "data" : {
    "id" : "12",
    "type" : "tasks",
    "name" : "someTask",
    "schedule" : {
      "data" : null,
      "links" : {
        "self" : "http://localhost:8080/tasks/12/relationships/schedule",
        "related" : "http://localhost:8080/tasks/12/schedule"
      }
    },
    "project" : {
      "data" : {
        "id" : "1",
        "type" : "projects",
        "name" : "someProject"
      },
      "links" : {
        "self" : "http://localhost:8080/tasks/12/relationships/project",
        "related" : "http://localhost:8080/tasks/12/project"
      }
    }
  }
}

Crnk supports versioning via content negotiation using the HTTP Accept header or a URL parameter. This allows you to evolve your API without changing URLs.

How it works:

• Annotate resources and fields with @JsonApiVersion to specify a version range.
• Crnk will only include resources/fields if their version range intersects with the requested version.
• Versions are integer-based (representing major versions).

Requesting a version:

Via Accept Header: GET /api/versionedTask HTTP/1.1
Accept: application/vnd.api+json; version=2

Via URL Parameter: GET /api/versionedTask?version=2 HTTP/1.1

Limitations:

• ID fields cannot be versioned.
• Meta and link fields cannot be versioned (currently).
• You cannot use multiple classes to serve the same resource for different version ranges; instead, redefine fields within the class.

@JsonApiResource(type = "versionedTask")
public class VersionedTask {
  @JsonApiVersion(min = 1, max = 3)
  private boolean completed;

  @JsonApiVersion(min = 4)
  @JsonProperty("completed")
  private CompletionStatus newCompleted;
}