Liferay is an open source platform started in 2000, long before the term “Web API” existed. One early characteristic of Liferay has been its great extensibility, which included providing a featureful HTTP API to access its functionalities since the very beginning. Initially this API used SOAP (as well as other less used protocols). Later a new “RESTful” option was added, leveraging HTTP+JSON and it became much more popular (even though it was at Level 0 in Richardson Maturity Model). However, both approaches lead users of the API to have a high coupling that makes the evolution of the APIs a challenging task. So we started wondering, isn’t there a better way to build APIs in 2017?
This session explains our search to find a better alternative and what we learned along the way.
It focuses on how we have adopted Hypermedia and Shared Vocabularies to create a new breed of APIs that we believe form the secret ingredients that solve the most important challenge we have in the API Economy: evolvability. We are now successfully applying this type of APIs in all of our products, on premise, cloud based, … even internal.
We have found that once you know how and build some common foundation, all the barriers to build evolvable APIs disappear. We learned from many others along the way and want to contribute back by sharing our experience.
12. “REST”-API: JSON Web Services
● Automatic generation of an HTTP+JSON Web API
from a Java API
● Auto-generated interactive documentation
● Batch operations
14. Conclusions - The Good
Very comprehensive , 90+% of the platform’s
functionalities
✓
More developer friendly
Interactive docs, batch operations, ... were highly
appreciated ⇒ More adoption
✓
✓
15. Conclusions - The Ugly (1/2)
Certain APIs were very difficult to consume
●
✘
✘ Custom technology. Requires learning just for Liferay
16. Conclusions - The Ugly (2/2)
Internal changes auto-propagated ⇒ Consumers were
broken in every release
●
✘
✘Increasingly perceived as bad/old API in comparison
●
17. We also tried a “competing” approach!
● AtomPub (With Shindig)
○ Fully RESTful
○ Atom XML
● Mapping Layer
○ Manual Coding
23. 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
85. 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