The liferay case: lessons learned evolving from RPC to Hypermedia REST APIs

The Liferay case
Lessons learned evolving from
RPC to Hypermedia REST APIs

This slides are already available at
bit.ly/liferay-hypermedia-api

Who are
we?
VP of Engineering|
Jorge Ferrer|
Software Engineer|
Alejandro Hernández|

Liferay is a software provider
Open Source APIsOn-Premise + Cloud
Digital Experiences Web, Mobile, ...Platform

Key usages of APIs in Liferay
1 Integration
Omni-channel consumers
Web Applications
2
3

Conclusions - The Good
Enabled the possibility of integration with external
systems
✓
Easy to build APIs thanks to code generation from
Java APIs
✓

Conclusions - The Ugly
Compatibility problems✘
Hard to consume APIs
Strong dependency on tooling
⇒ Poor adoption
✘
✘

REST-API“ ”
mmm….
We mean RPC over HTTP

“REST”-API: JSON Web Services
● Automatic generation of an HTTP+JSON Web API
from a Java API
● Auto-generated interactive documentation
● Batch operations

We were here
Richardson Maturity Model - Martin Fowler
Is that bad?

Conclusions - The Good
Very comprehensive , 90+% of the platform’s
functionalities
✓
More developer friendly
Interactive docs, batch operations, ... were highly
appreciated ⇒ More adoption
✓
✓

Conclusions - The Ugly (1/2)
Certain APIs were very difficult to consume
●
✘
✘ Custom technology. Requires learning just for Liferay

Conclusions - The Ugly (2/2)
Internal changes auto-propagated ⇒ Consumers were
broken in every release
●
✘
✘Increasingly perceived as bad/old API in comparison
●

We also tried a “competing” approach!
● AtomPub (With Shindig)
○ Fully RESTful
○ Atom XML
● Mapping Layer
○ Manual Coding

Lessons
1. API generation means
✓ Less work and more comprehensiveness
✘ Deep coupling
2. Importance of features for consumer devs

In search of a better
solution

Our two key challenges
Developer
Experience
Change
Management
Evolution

Consumer?
API v3API v1 API v2 API v4

The cost of breaking changes
For consumer devs
● Being forced to
change code with
each new version
For API devs
● Visible: Keep several
API versions alive
● Hidden: Avoid change
to reduce visible cost

Are we really the only
ones with this problem?

Is hypermedia really
feasible or is it a utopia?

What is the *best* format
for the API responses?
JSON or XML?
Or should it be
binary?
HAL, JSON-LD, Siren, JSON-API, …?

Is REST dead and should
we go with GraphQL?

Learning from the best
1. The most popular “API
Guidelines”
2. Tons of articles and
several books.

Books that made a
difference for us

The liferay case: lessons learned evolving from RPC to Hypermedia REST APIs

APIs designed to evolve
How we are solving each of the challenges

1. Hypermedia Controls
Home URL Link TypesAffordance Types

{
"_embedded": {...},
"total": 43,
"count": 30,
"_links": {
"first": {
"href": "http://localhost:8080/o/api/p/groups?page=1&per_page=30"
},
"next": {
},
"last": {
}
}
}
HAL
Pagination

{
“properties”: {
“title”: “Hypermedia is awesome”,
…
}
  "actions": [
      {
          "name": "delete-item",
          "title": "Delete Blog Posting",
          "method": "DELETE",
          "href": "http://localhost:8080/o/p/blogs/abcdef",
      }
      {
          "name": "publish",
          "title": "Publish Blog Posting",
          "method": "POST",
          "href": "http://localhost:8080/o/p/123URLs4123AREabcdeOPAQUEf41231",
      }
…
Actions
SIREN

Forms
{
  ..
  "actions": [
      {
          "name": "add-blog-posting",
          "title": "Add Blog Posting",
          "method": "POST",
          "href": "http://localhost:8080/o/p/blogs",
          "type": "application/json",
          "fields": [
              { "name": "headline", "type": "text" },
              { "name": "author", "type": "Person" },
          ]
      }
  …
SIREN

2. Shared Vocabularies
Standard types Well defined custom types

Defining types
most important API design activity

Communicating the types
OpenAPI JSON Schema ALPS
Profile ⇒

Goal: The smallest contract possible
● One single URL
● Message types
● Affordance types

Is hypermedia really feasible or is it a
utopia?

What is the *best* format for the API
responses?

Is REST dead and should we go with
GraphQL?

Project: Microservice APIs
API stack: Java with Spring
Consumers: Java Microservice, Mobile App
1

Home URL
{
name: "pulpo-api",
description: "API for consuming PULPO Services",
_links: {
self: { href: "http://localhost:8084/" },
accounts: {
href: "localhost/{projectId}/accounts{?filter,page,size,sort*}",
templated: true
},
account: {
href: "localhost/{projectId}/accounts/{identifier}",
templated: true
},
fields: {
href: "localhost/{projectId}/fields{?filter,page,size,sort*}",
templated: true
},
field: {
href: "localhost/{projectId}/fields/{identifier}",
templated: true
},
}
}
HAL

{
"dateCreated":"2017-11-15T16:23:35Z",
"dateModified":"2017-11-15T16:23:35Z",
"identifier":"AV_Afi6-Y3UMLZEdmkBE",
"name":"Friends",
"segmentType":"STATIC",
"status":"ACTIVE",
"_links":{
"self":{
"href":"http://localhost:8084/my-project/individual-segments/AV_Afi6-Y3UMLZEdmkBE"
},
"individual-segments":{
"href":"http://localhost:8084/my-project/individual-segments{?filter}",
"templated":true
}
}
}
HAL
Affordance Types

@GetMapping(
produces = {MediaType.APPLICATION_JSON_VALUE, "application/hal+json"},
value = "/{identifier}"
)
public @ResponseBody Resource<Individual> findOne(
@PathVariable String projectId, @PathVariable String identifier) {
IndividualEntity individualEntity = _individualService.findOneByUUID(
projectId, identifier);
if (individualEntity == null) {
throw new NotFoundException(
"Unable to find Individual with individualUUID " + identifier);
}
return _individualResourceAssembler.toResource(individualEntity);
}
Affordance Types

[
{
"title": “We are in APIConference!”,
"subtitle": “APIConference”,
"user": “localhost:8080/o/p/30325”
},
{
"title": “5 amazing things!”,
"subtitle": “Get english!”,
}
]
localhost:8080/o/api/blogs?start=25&end=27
[
{
"headline": “We are in APIConference!”,
"alternativeHeadline”: “APIConference”,
"author": “localhost:8080/o/p/30325”
},
{
"headline": “5 amazing things!”,
"alternativeHeadline": “Get english!”,
"author": “localhost:8080/o/0/65443”
}
]

{
“count”: 2,
“totalItems”: 30,
“members”: [
{
"headline": “We are in APIConference!”,
"alternativeHeadline": “APIConference”,
"author": “localhost:8080/o/p/30325”
},
{
"headline": “5 amazing things!”,
"alternativeHeadline": “Get english!”,
"author": “localhost:8080/o/0/65443”
}
],
“view”: {
“next”: “localhost:8080/blogs?p=7&p_p=2”
}
}
localhost:8080/o/api/blogs?page=6&per_page=2
[
{
"title": “We are in APIConference!”,
"subtitle": “THE conference for APIs”,
},
{
"title": “5 amazing things to do in
London!”,
"subtitle": “Get english!”,
"user": “localhost:8080/o/0/65443”
}
]

How do I add support for
queries?

Project: Platform APIs
API stack: Java with OSGi and JAX-RS
Consumers: Mobile Apps, Think Web clients, ESBs,
Legacy Apps, ...
2

Home URL
{
"resources": {
"blog-postings": {
"href": "http://localhost:8080/p/blog-postings"
},
"web-sites": {
"href": "http://localhost:8080/p/web-sites"
},
"documents": {
"href": "http://localhost:8080/p/documents"
},
"organizations": {
"href": "http://localhost:8080/p/organizations"
},
"people": {
"href": "http://localhost:8080/p/people"
}
}
}
JSON-HOME

Affordance Types
{
"@context": [
{ "creator": { "@type": "@id" } },
{ "@vocab": "http://schema.org/" },
"https://www.w3.org/ns/hydra/core#"
],
"@id": "http://localhost:8080/p/blog-postings/0",
"@type": "BlogPosting",
"alternativeHeadline": "Et eaque quod.",
"articleBody": "Sunt adipisci eligendi dolorem ducimus placeat.",
"creator": "http://localhost:8080/p/people/9",
"dateCreated": "2017-07-11T11:06Z",
"dateModified": "2017-07-11T11:06Z",
"headline": "Alone on a Wide, Wide Sea"
}
JSON-LD + HYDRA

Affordance Types
{
"@id": "http://localhost:8080/p/blog-postings/0",
"@type": "BlogPosting",
"creator": "http://localhost:8080/p/people/9",
"headline": "Alone on a Wide, Wide Sea",
"operation": [
{
"@id": "_:blog-postings/delete",
"@type": "Operation",
"method": "DELETE"
},
{
"@id": "_:blog-postings/update",
"@type": "Operation",
"expects": "http://localhost:8080/f/u/blog-postings",
"method": "PUT"
}
]
}
JSON-LD + HYDRA

Affordance Types
{
"@id": "http://localhost:8080/f/u/blog-postings",
"@type": "Class",
"description": "This can be used to create or update a blog posting",
"supportedProperty": [
{
"@type": "SupportedProperty",
"property": "creator",
"required": false,
},
{
"@type": "SupportedProperty",
"property": "headline",
"required": true,
}
],
"title": "The blog posting form"
}
JSON-LD + HYDRA

public Representor<BlogPostingModel, Long> representor(
Builder<BlogPostingModel, Long> builder) {
return builder.types(
"BlogPosting"
).identifier(
BlogPostingModel::getId
).addDate(
"dateModified", BlogPostingModel::getModifiedDate
).addLinkedModel(
"creator", PersonId.class, BlogPostingModel::getCreatorId
).addRelatedCollection(
"comment", BlogPostingCommentId.class
).addString(
"alternativeHeadline", BlogPostingModel::getSubtitle
).addString(
"articleBody", BlogPostingModel::getContent
).addString(
"headline", BlogPostingModel::getTitle
).build();
}
Well defined custom types

Project: Data Integration
through ETL/ESB
Consumer: Talend Plugin
3

Your needs > Any specific solution

Spend time defining your vocabulary

Make consumers & their developers the
focus of your API design strategy
● Provide features that make their job easier
● APIs should speak their language, not yours

Apio: An Open Source Project
Apio Architect
●
●
Apio Consumer
○
○

The liferay case: lessons learned evolving from RPC to Hypermedia REST APIs

More Related Content

What's hot (16)

Similar to The liferay case: lessons learned evolving from RPC to Hypermedia REST APIs (20)

Recently uploaded (20)

The liferay case: lessons learned evolving from RPC to Hypermedia REST APIs