By Aaron Klish & Jon Kilroy

Mobile and client-side web applications have been reshaping the design principles of service layer APIs. Business logic traditionally implemented on the server and exposed as functions (think RPC) has morphed into exposing data and shifting that logic to the application. Object hierarchies and graphs are one of the most common and natural forms for data representation and often pair well with simple CRUD (create, read, update, & delete) operations. The main challenges with building these services is that powerful & flexible APIs that expose data are often expensive to build. There is usually only time to build the minimal set of interfaces that are needed by a single application.

Elide is a new Yahoo technology designed to significantly reduce the development cost to expose a hierarchical data model as a production quality REST API. Elide adopts the best standards to date for API definition targeting the concerns of front end developers - JSON-API.

What Is JSON-API

JSON-API is a standard for representing and manipulating an entity relationship graph through a REST API.

Oversimplifying things, the path segment of URLs in JSON-API are constructed by:

1. Referencing collections of entities at the root by type: /books
2. Referencing individual entities: /books/1
3. Referencing collections of entities through a relationship: /books/1/authors or /books/1/relationships/authors

Entity representations consist a type, an ID, a set of attributes, and a set of relationships to other entities:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

"data": {
  "id": "12345678-1234-1234-1234-1234567890ab",
  "type": "author",
  "attributes": {
    "name": "Ernest Hemingway"
  },
  "relationships": {
    "books": {
      "data": [
        {
          "type": "book",
          "id": "12345678-1234-1234-1234-1234567890ac"
        },
        {
          "type": "book",
          "id": "12345678-1234-1234-1234-1234567890ad"
        }
      ]
    }
  }
}

Modeling Your Data

JSON-API needs a data model to expose. Rather than starting from scratch with a new DSL, we adopted the most mature, feature rich, and industry proven data modeling framework for the backend - JPA (Java Persistence API). JPA allows developers to define complex models but also to leverage existing providers for a wide variety of persistence architectures - or to build their own custom solutions. We’ve done both at Yahoo. Elide exposes any JPA annotated data model as a complete, JSON-API web service.

Filling the Gaps

Having a powerful API and a powerful modeling language are not enough to build a production quality service. There are four other components that are required to expose data as a service:

1. Security - With Elide, the developer first chooses which entities to expose and which to leave hidden. Elide then provides new annotations that work alongside JPA to define completely customizable authorization policies for every exposed entity, attribute, relationship, and operation. Like the data model itself, authorization is hierarchical. The path taken to reach an object in the hierarchy determines the security checks invoked, reducing the need to duplicate security rules. Unlike other data as a service frameworks (GraphQL, Falcor, etc.), authorization of data is a first class property of the data model itself.
2. Data Validation - Data validation can take the form of simple constraints like a field shouldn’t be null. It can also involve complex rules where two or more entities must be changed together or not at all. Part of the rationale to leverage JPA was its powerful set of aspect oriented validation annotations and APIs.
3. Consistency - Clients need a consistent representation of the object graph that doesn’t interleave operations across users. JSON-API has bulk read (compound documents) and write (PATCH extension) interfaces. These interfaces coupled with transactions that wrap every API request enable the client to build and maintain a consistent view of their data.
4. Extension - Elide provides hooks for customizing the behavior of data model operations, for wiring in new persistence architectures, and for exposing functions as attributes in the model.

The marriage of JSON-API, JPA, and a custom set of Elide annotations provide other benefits:

1. Round Trip Reduction - JSON-API provides the ability to query an individual entity - but also ask for its children, grandchildren, and so on in the form of compound documents. It also supports bulk write interfaces to perform a series of updates in a single request.
2. Type Safety - While JSON-API is not strongly typed, JPA is. Elide ensures that the provided JSON conforms to the underlying data types of the model.
3. Query Projection - JSON-API allows the client to specify the exact subset of elements it wants returned from the data model. This feature is critical for the performance of the persistence layer and also reduces the total payload of data sent back to the client.
4. Web Compatible - Facebook has recently released GraphQL - another technology in this space with a similar set of goals. Unlike GraphQL, Elide embraces the web architecture and REST. Elide is fully compatible with traditional web caching that is fundamental to reduce client latency.

Future Work

Elide is working on the release of other features including:

1. A fluent, JavaScript library (although Elide already works with existing JSON-API clients).
2. A test framework that makes security verification as simple as setting up an Elide service.
3. Introspection capabilities that will allow powerful validation for clients, documentation, and other tools.

For now, check out our documentation at elide.io. We hope to have more posts soon with some tutorials for simple projects.