Roy Fielding’s dissertation where REST was originally presented was published over 17 years ago. And yet, most developers have a really hard time understanding it. It’s also very common for articles and even books present a partial and/or inaccurate view of what REST is. Additionally there are frequently claims by “experts” that REST is not well defined or that a “Pragmatic REST” approach is the most desired. In these approaches, Hypermedia is often fully discarded, even if it’s a formal requirement for REST. In addition to this, when teams design an API countless hours are spent in discussions talking about whether a given URL is restful or not. Meanwhile, very few of these API developers and designers seem to focus on one of the most important goals of the Representational State Transfer architectural style: to create APIs designed to evolve by decoupling the individual systems. Is there a solution for this?

At Liferay we have been designing APIs for our Open Source products for 14+ years and have gone through many architectural styles and technologies (RMI SOAP, Burlap, Hessian, JSON+HTTP RPC, Resource Oriented, …). In 2017 we started a project with the goal of solving the evolvability challenges we had been facing all this time. As a result we have come up with a new set of API guidelines that strongly leverage REST (yes, including Hypermedia), Shared Vocabularies (using schema.org and others as a foundation), the representor pattern and with a strong focus on standards.

The next challenge has been, how can we make it easier for our developers to develop APIs that conform to these standards? Most of our development is done in Java so we started leveraging the most popular frameworks like JAX-RS and Spring REST (incl. Spring HATEOAS). While these frameworks have made building Evolvable APIs possible, it wasn’t really so easy and a lot of boilerplate code was often needed. Also, developers needed quite a bit of training. To simplify things we started extracting the most common pieces and created an Open Source library out of it: Apio Architect.

Apio Architect (https://github.com/liferay/com-liferay-apio-architect) has evolved a lot during these past few months and while it was not our original intention, it has ended up providing an abstraction layer over the underlying “REST” framework (JAX-RS to beging with). This abstraction has the following characteristics: * It ensures that the resulting API is fully RESTful, making proper use of URLs as identifiers and HTTP’s verbs as designed. * Abstracts away the design of the URLs, so that developers done have to spend countless hours discussing about them. * It facilitates the creation of affordances, such as links among related resources or forms for creation or addition operations. * It implements the representor pattern and provides out of the box support for some representations (HAL with HAL-FORMS, JSON-LD+Hydra, …) * It allows the developer to code in the terms of a human-language spec and have the framework translate it for you.

The current version of Apio Architect does not yet offer a full abstraction layer, but we are beginning to think it is possible to do so. In this session we would like to present our progress so far with the framework and some APIs built with it and present our plans moving forward to the wider Web API community.