Are Hypermedia APIs Just Hype? - Aaron Phethean (Temenos) & Daniel Feist (MuleSoft)
Making Sense of Hypermedia APIs – Hype or Reality?
Transcript of Making Sense of Hypermedia APIs – Hype or Reality?
© 2015 Akana., Inc All Rights Reserved.
Making Sense of Hypermedia APIs – Hype or Reality
Laura [email protected]@akana.com
© 2015 Akana., Inc All Rights Reserved.
The Glory of REST
Richardson’s Maturity Model
Roy Fielding definition of RESTFulHATEOAS
/books/1 and /books/2
http://martinfowler.com/articles/richardsonMaturityModel.html
GET, PUT, POST, DELETE
POST
© 2015 Akana., Inc All Rights Reserved.
What is HATEOAS
• Response include hypermedia links to navigate the restful interface
• Each link is presumed to support REST verbs of GET, POST, PUT, DELETE or subset
Hypermedia as the Engine of Application State
© 2015 Akana., Inc All Rights Reserved.
WebSites are Broken into Two Parts
HTML
Data (JSON/XML)
https://www.youtube.com/watch?v=vioCbTo3C-4
© 2015 Akana., Inc All Rights Reserved.
HTML Provides Standard We all Adhere To
Many clients understand and can interpret HTML
Many Extensions to enhance the HTML document experience across the web, that most clients can understand
Changing your HTML should not break your client
© 2015 Akana., Inc All Rights Reserved.
What About The Data?
What are the standard to Link the Data?
Where Are the Clients?
(JSON/XML)When we change our APIs the clients break!!
© 2015 Akana., Inc All Rights Reserved.
Hypermedia Standards Attempts are Born
• General Hypermedia Media Types– Collection+Json– Hal– Json-LD– JsonAPI– Mason– OData– Siren– Uber– And More …..
• Industry Media Types– FHIR – Healthcare HL7 restful representation– VoiceXML
• API Media Types– GitHub– Heroku
© 2015 Akana., Inc All Rights Reserved.
What are General Hypermedia TypesBorn Created By Goals
Odata 2010 Microsoft 2010 (v1,2,3)
OASIS 2014 (4,5,6)
• Started as a data API for Microsoft Azure.
Collection+JSON 2011 Mike Amundsen • Management and querying of simple collections
HAL – Hypertext Application Language
2011 Mike Kelly • Simple way to hyperlink between resources
Siren 2012 Kevin Swiber • Hypermedia specification for representing entities• Offers structures to communicate information about entities,
action for executing state transitions and links for client navigation.
JsonAPI 2013 Steve Klabnik, Yehuda Katz
Dan GebhardtTyler Kellen
• A generic media type that can work across a broad set of use cases, including generally used relationship types.
• Designed to minimize both the number of request and amount of data transmitted between clients
JSON-LD + Hydra 2013 W3CMarcus Lanthaler;
et al
• It is primarily intended to be a way to use Linded Data in Web-based programming environments, to build interoperable web services, and to store Linked Data in JSON-based storage engines.
Mason 2014 Jorn Wildt • Hypermedia elements for linking and modifying data, features for communicating to client developers and standardized error handling. Based off of HAL but introduces Actions and Error handling
UBER 2014 Mike AmundsenSteve Klabnik
• Moving beyond HTTP. It is protocol agnostic.
© 2015 Akana., Inc All Rights Reserved.
What to Look for in a Generic Hypermedia Types
Links
Get
Post
DELETE
Put
Actions Profile
© 2015 Akana., Inc All Rights Reserved.
What Is Supported Media Types XML JSON Actions Profiles
Odata application/jsonapplication/atom+xml
application/atomsvc+xmlapplication/xml
x x
Collection+JSON Application/vnd.collection+json x xHAL – Hypertext Application Language
application/hal+jsonapplication/hal+xml
x x x
Siren application/vnd.siren+json x x x x
JsonAPI application/vnd.api+json x x
JSON-LD application/ld+json x (when used with hydra) x
Mason application/vnd.mason+json x x x
UBER application/vnd.uber-amundsen+xml
application/vnd.uber-amundsen+json
x x x x
© 2015 Akana., Inc All Rights Reserved.
Tools And Clients AvailableCommunity
ActivitySocial
Mentions in API
Community
Tools Reference Available Tools
OdataHigh Low http://www.odata.org/
ecosystem/• Server side tools : Several - too many to list• Client tools: Several - too many to list• Clients: Several - too many to list
Collection+JSONLow Low https://github.com/collection-
json• Server side tools : Limited• Client tools: Limited• Clients: Limited
HAL – Hypertext Application Language High High https://github.com/mikekelly/
hal_specification/wiki/Libraries
• Server side tools: Several - too many to list• Client tools: Several - too many to list• Clients: Several - too many to list
SirenLow Medium
https://github.com/search?utf8=%E2%9C%93&q=Siren+hypermedia
• Hard to find. Not as easily found as there is no single page being maintained listing the tools
JsonAPIMedium Low http://jsonapi.org/
implementations/
• Server side tools : Good Base• Client tools: Several – Good Base• Clients: Good Base
JSON-LDMedium Medium
https://github.com/search?q=JSON-LD&type=Repositories&utf8=%E2%9C%93
• Great interactive tool on http://json-ld.org/• Several GitHub repositories – but not organized
as well. Hard to find
Mason Low (very new) Low (very new) • Very new
UBERLow(very new) Low(very new)
https://github.com/search?utf8=%E2%9C%93&q=UBER+hypermedia
• Very new. Limited
© 2015 Akana., Inc All Rights Reserved.
Siren Example
Specifies Actions:• what actions you can
preform• what is required to do so.
Specifies Navigation
Embedded Entities:• Order contains two
embedded entities• Contains links to get to the
embedded entities
The Resource
© 2015 Akana., Inc All Rights Reserved.
JsonAPI ExampleCompound Documents:• Reduce number of HTTP
requests
Simple Get Document
Linkage
© 2015 Akana., Inc All Rights Reserved.
API DL Serve 4 Aspects
• Blueprint for how to design your APIs
• Contract between you and the API consumers especially in the design phase.
• Metadata for communicating API capability with other systems.
• Human readable documentation, interpreted by tooling such as swagger and raml to produce browser html.
* Doesn’t matter what type of API you are
© 2015 Akana., Inc All Rights Reserved.
Does Hypermedia Serve these Aspects?
• Blueprint – Hypermedia dictates the structure of you APIs – figuring out the backend systems and data model becomes the most difficult part.
• Contract – Hypermedia doesn’t really have anything here.
• Metadata – If there were standard then this would be taken care of because everything would be a client. However, this is not so today.
• Human readable - Hypermedia API by itself is not human readable though some will argue it is. It is missing the ability
© 2015 Akana., Inc All Rights Reserved.
What Does Hypermedia Mean for API DL
API DL are still necessary - at least for a while• It is what developers expect when viewing APIs
• Though hypermedia client browsers like HalTalk are a good start• API DLs provide schema’s and examples for the APIs
• Most enterprise systems (security gateways, cloud integration) and tools (testing tool) are not hypermedia clients.• They do understand API DL
• Hypermedia can’t act as a contract between provider and consumer
Describe you hypermedia API with a API DL
© 2015 Akana., Inc All Rights Reserved.
Arguments for Hypermedia APIs
• API are more flexible
• Won’t break the client **
• Enables discoverability
• Replaces the Need for Documentation
• Is true Roy Fielding REST
© 2015 Akana., Inc All Rights Reserved.
Arguments Against Hypermedia
• Creates More Work
• Requires more Data-Transfer
• Creating an API for a client that doesn’t exist
• No one knows how to use Hypermedia
• Limited tools available
• No clear leader in which hypermedia standard to use
© 2015 Akana., Inc All Rights Reserved.
Are you Already Using Some Hypermedia Concepts?
Have you ever needed to change something:• But didn’t have access to the production systems • It was too expensive (time and money) to constantly redeploy product
code?• Maybe, even you wanted to change something after a certification?
IMAGESPagination
http://www.infoq.com/articles/implementing-hypermedia
© 2015 Akana., Inc All Rights Reserved.
Are You Ready For Hypermedia?
http://www.infoq.com/articles/implementing-hypermedia
“While much of the theory of hypermedia talks about hypermedia as the fundamental, underlying theory of your entire API, I have a little secret to share with you: it doesn't have to be that way. You can gain some of the advantages of hypermedia without doing an entire overhaul of your API” – Steve Klabnik
© 2015 Akana., Inc All Rights Reserved.
What Are Your Options for Adopting Hypermedia?
1. Do nothing stay at level 2 maturity and wait for a clear standard to emerge
2. Continue employing hypermedia concepts as needed
3. Create you own company specific media type (example GitHub)
4. Propose an industry hypermedia type and register it with IANA ( example FHIR)
5. Adopt one of the basic & simplistic standards that focus only on the links such as HAL, Siren or JsonAPI. Add your own extensions
6. Adopt one of the more forward thinking hypermedia type such as UBER, JSON-LD/Hyrda
© 2015 Akana., Inc All Rights Reserved.
API Resources and API University
• Resource Center– http://resource.akana.com/
• Follow us on:
https://www.linkedin.com/company/akana
https://twitter.com/AkanaInc