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


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


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

Laura Heritage

Now that you have seen the Maturity levels and understand what Hateoas is. What do you think your maturity level is in general?


How The Web Works Today

Link

Link


WebSites are Broken into Two Parts

HTML

Data (JSON/XML)

https://www.youtube.com/watch?v=vioCbTo3C-4


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


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!!


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


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.


What to Look for in a Generic Hypermedia Types

Links

Get

Post

DELETE

Put

Actions Profile


Profiles Give Context and Meaning To the Data

RFC6906


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


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

http://json-ld.org/


OData Example


Collection+JSON Example


Hal Example


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


JsonAPI ExampleCompound Documents:• Reduce number of HTTP

requests

Simple Get Document

Linkage


JSON-LD


Mason Example

Actions


UBER Example

Actions

Profile


What Does Hypermedia Mean for API DL


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


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


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


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


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


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


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


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


API Resources and API University

• Resource Center– http://resource.akana.com/

• Follow us on:

https://www.linkedin.com/company/akana

https://twitter.com/AkanaInc

http://resource.soa.com/

http://resource.soa.com/

https://www.linkedin.com/company/akana

https://twitter.com/AkanaInc

making sense of hypermedia apis – hype or reality?

Internet

rights r

hypermedia links

general hypermedia types

data api

subset hypermedia

linked data

linded data

data rfc6906