This is the presentation I delivered at the Liferay North American Symposium 2017 and presents our vision for making Liferay the best Headless Platform out there.
It specifically covers how we are using the power of Hypermedia + Shared Vocabularies to build APIs designed to evolve and extremely easy to use and consume
1. Liferay as a Headless Platform
Introducing a New Breed of Secure Hypermedia APIs
Jorge Ferrer, VP Engineering
Michael Han, VP Operations
2. @jorgeferrer #LSNA17
H e a d l e s s s o f t w a r e i s s o f t w a r e c a p a b l e o f
w o r k i n g w i t h o u t a g r a p h i c a l u s e r i n t e r f a c e
W i k i p e d i a
“
6. @jorgeferrer #LSNA17
Th e A P I e c o n o m y i s a n e n a b l e r f o r t u r n i n g
a b u s i n e s s o r o r g a n i z a t i o n i n t o a p l a t f o r m .
P l a t f o r m s m u l t i p l y v a l u e c r e a t i o n .
G a r t n e r
“
15. #LRDEVCON
Liferay to be an OAuth 2.0 provider
Giving end-users the ability to delegate permissions to
apps
• An authorization protocol for web APIs
• Protocol widely adapted on the web
• Multiple authorization granting flows available
16. #LRDEVCON
Authorization
Resource Owner – the User
Client – a client application (e.g. mobile application)
Authorization Server – Issues access token for clients
approved by the owner.
Resource Server – API server providing API resources
18. #LRDEVCON
For applications to authenticate on behalf of itself
Useful when getting non-user specific information from the portal
Easy migration from legacy API authentication schemes (Basic, Digest etc.)
Client Credential grant flow
1. Client ID & Client Secret
2. Access token
19. #LRDEVCON
2. Resource Owner Password Credentials
3. Access token
Resource Owner Credentials grant flow
1. Resource Owner Password
Credentials
Simple authentication by providing username & password
Exchanged for access token, no password storage. Suitable for trusted
first party clients.
21. #LRDEVCON
User’s trust boundary
What happened to my users?
User trust issues with providing password
Only suitable for 1st party web and mobile applications
2. Resource Owner Password Credentials
3. Access token
1. Resource Owner Password
Credentials
22. #LRDEVCON
Authorization Code grant flow
Best option for webserver and
User agent apps
No username & password
given to app
Can be used for mobile apps,
but requires popping a web
browser
User’s trust boundary
5. Access token
2. User
authenticates &
authorizes
4. Authorization Code &
Redirect URI
1. Client ID &
Redirect URI
3. Authorization
code
23. #LRDEVCON
Pre-Authorized tokens for devices
Building a unified experience across multiple devices
• Maintaining a fully native experience for each
device
• Generate pre-authorized tokens via a web portal
• Mobile app receives the token via
• Onscreen QR code scanned with camera
25. #LRDEVCON
One protocol to unify them all!
OAuth 2.0 provider allows API authentication
via all new and existing web SSO solutions
available to Liferay Portal
• Authorization Code grant flow
• Pre-Authorised tokens
27. #LRDEVCON
Service Access Quotas
• Important for building large scale systems with untrusted clients
• Protect against service abuse
• Extracts characteristics of API requests and matches against
configured quotas
• For example
• allow 100 requests
• to a service method
• within 5 minutes
• for each client IP address and User ID combination
32. @jorgeferrer #LSNA17
Reduce the
need for
documentation
Embrace
REST
Best Practices
Adopt
Standards
Abstract
Liferay
Internals
HOW?
Promote
Reusability
35. @jorgeferrer #LRDEVCON
Hypermedia Controls
Single Endpoint
Consumers only know the
home URL
And are able to interpret the
listed resources
Standardized Link Types
Consumers can follow links
whose type is known
IANA standardizes many of them
We can add more on top
36. @jorgeferrer #LSNA17
{
"resources": {
"people": {
"href": "http://api.domain.io/o/api/p/people"
},
"organizations": {
"href": "http://api.domain.io/o/api/p/organizations"
},
[..]
"sites": {
"href": "http://api.domain.io/o/api/p/sites",
"hints": {
"media-type": "application/ld+json"
}
}
}
}
A Single Home Endpoint
http://api.domain.io/o/api
Consumers become
inmune to changes
in URLs
JSON Home Internet Draft
37. @jorgeferrer #LSNA17
{
"_embedded": {...},
"total": 43,
"count": 30,
"_links": {
"first": {
"href": "http://localhost:8080/o/api/p/groups?page=1&per_page=30"
},
"next": {
"href": "http://localhost:8080/o/api/p/groups?page=2&per_page=30"
},
"last": {
"href": "http://localhost:8080/o/api/p/groups?page=2&per_page=30"
}
}
}
Hypermedia pagination
Consumers become
simpler, leaving
logic to the server
IANA Link Relations Standard
38. @jorgeferrer #LSNA17
{
..
"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" },
]
}
],
…
}
Forms in APIs
Consumers don’t
hardcode the fields
or types
Siren
39. @jorgeferrer #LRDEVCON
Standard Models (aka Shared Vocabularies)
schema.org and others
schema.org: 597 types and 867
properties
ActivityStreams, microformats,
…
Well defined custom Models
Don’t just expose your internal
models
Thinking terms through
40. @jorgeferrer #LSNA17
Mapping internal terms to standards
Internal schema.org
User + Contact Person
birthday birthDate
middleName additionalName
screenName alternateName
emailAddress email
lastName familyName
firstName givenName
fullName name
Internal schema.org
BlogsEntry BlogPosting
headline title
alternativeHeadline subtitle
description description
user creator
user author
articleBody content
aggregateRating ratings
41. @jorgeferrer #LSNA17
Consumer devs
don’t need to know
Liferay internals,
which are now free
to evolve
Mapping internal terms to standards
Internal schema.org + custom
Group (site=1) WebSite
name name
groupKey alternateName
user creator
Ratings Service aggregateRatings
friendlyURL (_self) / (@id)
BlogsEntry Service blogs
manualMembership (open question)
43. @jorgeferrer #LSNA17
Ready for real world needs
Multi-language1
2
3
Embed multiple resources to
avoid chattiness
Decide which fields to return
Very efficient
HTTP caching
Binary response formats
Consumers control
the response
Accept-Language header
53. @jorgeferrer #LSNA17
Amazing results with our first Mobile App
80%+ of the code is
reusable
Vulcan Consumer
Thing Screenlet
Much easier to
provide offline
support
54. @jorgeferrer #LRDEVCON
02
03
Guidelines
Well documented guidance to build APIs
designed to evolve
01
Sharing with we have learned and built
Project codename Vulcan
Architect
Making a breeze to build modular
Hypermedia APIs
Consumer
Does all the repetitive work for
consuming a Hypermedia API
60. @jorgeferrer #LSNA17
Image Credits
This presentation has photos from Pana
Vasquez , Oumaima Ben Chebtit, Patrick
Tomasso, jesse orrico, Toa Heftiba, Jeremy
Thomas, John Mark Arnold, Linda Xu, 35mm, Todd
Quackenbush, Sawyer Bengtson, Jorge
Gonzalez, Justin Main, Vadim Sherbakov, Kimon
Maritz and Matt Jones on Unsplash
Thanks so much, for your amazing photos.