Json API

In some scenarios, JSON-API does not define how an implementation should behave. Elide also may not implement all optional features of the JSON-API specification. The following sections clarify Elide’s behavior with respect to undefined or optional aspects of JSON-API.

Hierarchical URLs

Elide generally follows the JSON-API recommendations for URL design.

There are a few caveats given that Elide allows developers control over how entities are exposed:

  1. Some entities may only be reached through a relationship to another entity. Not every entity is rootable.
  2. The root path segment of URLs are by default the name of the class (lowercase). This can be overridden.
  3. Elide allows relationships to be nested arbitrarily deep in URLs.
  4. Elide currently requires all individual entities to be addressed by ID within a URL. For example, consider a model with an article with a singular author which has a singular address. While unambiguous, the following is not allowed: /articles/1/author/address. Instead, the author must be fully qualified by ID: /articles/1/author/34/address

Filters

Filters are covered in this section.

Model Identifiers

Elide supports three mechanisms by which a newly created entity is assigned an ID:

  1. The ID is assigned by the client and saved in the data store.
  2. The client doesn’t provide an ID and the data store generates one.
  3. The client provides an ID which is replaced by one generated by the data store. When using the patch extension, the client must provide an ID to identify objects which are both created and added to collections in other objects. However, in some instances the server should have ultimate control over the ID that is assigned.

Data Store Generated IDs

Elide looks for the JPA GeneratedValue annotation to disambiguate whether or not the data store generates an ID for a given data model. If the client also generated an ID during the object creation request, the data store ID overrides the client value.

Matching newly created objects to IDs

When using the patch extension, Elide always returns object entity bodies (containing newly assigned IDs) in the order in which they were created. The client can use this order to map the object created to its ID.

ID types

ID fields must be Serializable objects. Elide does not require IDs to be UUIDs (a divergence from JSON-API).