Barcamp 2010: Why start a startup when you're young - Trung Huynh
Hypermedia: Why you need it, and why you're doing it wrong
-
Upload
michael-stowe -
Category
Technology
-
view
708 -
download
0
Transcript of Hypermedia: Why you need it, and why you're doing it wrong
l All contents Copyright © 2014, MuleSoft Inc.
• API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 10+ years hacking Professional Code
• Dev Relations Manager at MuleSoft
About Me
l All contents Copyright © 2014, MuleSoft Inc.
Poll: How many people are using or consuming Hypermedia based APIs?
l All contents Copyright © 2014, MuleSoft Inc.
Poll: What is your experience with hypermedia APIs like?
l All contents Copyright © 2014, MuleSoft Inc.5
The majority of today’s Hypermedia APIs follow this path:
• Make a call to a resource OR sub-resource
• Get back the collection or object with a list of related links
• Determine which resource you’re looking for
• Call that resource using the OPTIONS method to see what methods are available
• Call that resource
Typical Hypermedia Flow
l All contents Copyright © 2014, MuleSoft Inc.6
The majority of today’s Hypermedia APIs follow this path:
• Make a call to a resource OR sub-resource
• Get back the collection or object with a list of related links
• Determine which resource you’re looking for
• Call that resource directly using the method desired
• If no error, hard-code into your application
Typical Implementation of Hypermedia APIs
l All contents Copyright © 2014, MuleSoft Inc.7
The majority of today’s Hypermedia APIs follow this path:
• Look at the API’s documentation
• Get back the collection or object with a list of related links
• Determine the resource and method you’re looking for
• Hard code the resource and method into your application
Alternate Implementation of Hypermedia APIs
l All contents Copyright © 2014, MuleSoft Inc.
In other words, many of today’s implementations offer little to no benefit to developers – instead increasing their workload.
l All contents Copyright © 2014, MuleSoft Inc.
After all, hypertext has been known to us since 1965 when defined by Ted Nelson
l All contents Copyright © 2014, MuleSoft Inc.
And goes back as far as 1945when Vannevar Bush thought of the concept in his article “As We May Think”
l All contents Copyright © 2014, MuleSoft Inc.
In the simplest context, hypermedia is an extension of hypertext – or media that guides the user through a series of links
l All contents Copyright © 2014, MuleSoft Inc.24
a method of structuring information in different media for a single user… whereby related items are connected in the same way as a hypertext.
- Oxford English Dictionary
Hypermedia is…
l All contents Copyright © 2014, MuleSoft Inc.25
Hypertext is a computer-supported mediumfor information in which many interlinked documents are displayed with their links on a high-resolution computer screen.
- Jeffrey Conklin
Hypertext is…
l All contents Copyright © 2014, MuleSoft Inc.27
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
- Dr. Roy Fielding
l All contents Copyright © 2014, MuleSoft Inc.28
Representational State Transfer is made up of six primary constraints:
• Client/Server
• Stateless
• Cacheable
• Uniform Interface
• Layered System
• Code on Demand*
REST
l All contents Copyright © 2014, MuleSoft Inc.29
Hypermedia plays a role in:
• Client/Server
• Stateless
• Cacheable
• Uniform Interface
• Layered System
• Code on Demand*
REST + Hypermedia
l All contents Copyright © 2014, MuleSoft Inc.30
Hypermedia plays a role in:
• Client/Server
• Stateless
• Cacheable
• Uniform Interface
• Layered System
• Code on Demand*
REST + Hypermedia
l All contents Copyright © 2014, MuleSoft Inc.
Because REST is STATELESS, it has to have a way to REPRESENT state. That is the purpose of hypermedia, to act as the engine of state for the application.
l All contents Copyright © 2014, MuleSoft Inc.
Current State: Super User
Current State: Suspended User
Current State: Standard User
l All contents Copyright © 2014, MuleSoft Inc.
By describing application state, we are able to separate business rules from the client logic
l All contents Copyright © 2014, MuleSoft Inc.
This means your users’ shouldn’t have to guess your business logic, and aren’t at risk of application failure when you update your rules engine.
l All contents Copyright © 2014, MuleSoft Inc.
In other words, having hypermedia links in your response isn’t enough…they have to be meaningful.
l All contents Copyright © 2014, MuleSoft Inc.
This means giving equal weight to humans (ie developers/ integrators) and machines (servers, applications)
l All contents Copyright © 2014, MuleSoft Inc.
A machine can follow the links, but not necessarily understand them…
l All contents Copyright © 2014, MuleSoft Inc.
Which means your hypermedia links should be self-describing
l All contents Copyright © 2014, MuleSoft Inc.
This creates a problem as the leading hypermedia specifications are resource driven, and not action drive.
l All contents Copyright © 2014, MuleSoft Inc.48
JSON API
• Created by Steve Klabnik and Yahuda Klaz in 2013
• Designed to ensure separation between client and server
while also reducing the number of calls without impacting
discoverability
• JSON based
• One of the most popular specs
l All contents Copyright © 2014, MuleSoft Inc.49
JSON API
{"links": {"posts.author": {"href": "http://example.com/people/{posts.author}","type": "people"
},"posts.comments": {"href": "http://example.com/comments/{posts.comments}","type": "comments"
}},"posts": [{"id": "1","title": "Rails is Omakase","links": {"author": "9","comments": [ "5", "12", "17", "20" ]
}}]
}
l All contents Copyright © 2014, MuleSoft Inc.50
JSON API
Weaknesses:
• JSON only
• Lack of documentation
identifier
• Slightly more difficult for
clients to interpret
Strengths:
• Simple, versatile format
• Easy to read/ implement
• Flat link grouping
• URI templating
• Wide adoption
• Strong community
• Recognized as a Hypermedia
standard
l All contents Copyright © 2014, MuleSoft Inc.52
• Created by Mike Kelly in 2011
• Allows for nesting of links
• Supports JSON and XML
• Incorporates documentation
• One of the most popular specs
HAL
l All contents Copyright © 2014, MuleSoft Inc.53
HAL
{"_links": {
"self": { "href": "/orders" },"curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated":
true }],"next": { "href": "/orders?page=2" },"ea:find": {
"href": "/orders{?id}","templated": true
},"ea:admin": [{
"href": "/admins/2","title": "Fred"
}, {"href": "/admins/5","title": "Kate"
}]},
}
l All contents Copyright © 2014, MuleSoft Inc.54
Strengths:
• Dynamic/ Nestable
• Easy to read/ implement
• Multi-format (JSON/XML)
• URI Templating
• Inclusion of documentation
• Wide adoption
• Strong Community
• RFC proposed/ recognized spec
HAL
Weaknesses:
• JSON/XML formats
architecturally different
• CURIES (documentation) are
tightly coupled
l All contents Copyright © 2014, MuleSoft Inc.60
• Recognized as a W3C standard in 2014
• Designed as a linking format
• Can be used for both APIs and NoSQL
• Less popular than JSON API / HAL
• Very active community
JSON-LD
l All contents Copyright © 2014, MuleSoft Inc.61
JSON-LD
{"@context": "http://json-ld.org/contexts/person.jsonld","@id": "http://dbpedia.org/resource/John_Lennon","name": "John Lennon","born": "1940-10-09","spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}
l All contents Copyright © 2014, MuleSoft Inc.62
Strengths:
• Strong format for Data Linking
• Used across multiple formats
• Strong community
• Large working group
• W3C standard
JSON-LD
Weaknesses:
• JSON only
• More complex to
integrate/ interpret
• No identifier for
documentation
l All contents Copyright © 2014, MuleSoft Inc.
However, newer specifications are trying to become more descriptive and machine oriented.
l All contents Copyright © 2014, MuleSoft Inc.65
• Created by Kevin Swiber in 2012
• Created specifically for Web APIs
• Presents information on classes, entities, actions, and links
• Incorporates methods
• Supports JSON and XML
• Not as popular as JSON API and HAL
• Still a work in progress
Siren
l All contents Copyright © 2014, MuleSoft Inc.66
Siren{"class": [ "order" ],"properties": {
"orderNumber": 42, "itemCount": 3,"status": "pending"
},"entities": [{ "class": [ "items", "collection" ], "rel": [ "http://x.io/rels/order-items" ], "href": "http://api.x.io/orders/42/items"
},{"class": [ "info", "customer" ],"rel": [ "http://x.io/rels/customer" ], "properties": { "customerId": "pj123","name": "Peter Joseph"
},"links": [{ "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
]}
l All contents Copyright © 2014, MuleSoft Inc.67
Siren
"actions": [{"name": "add-item","title": "Add Item","method": "POST","href": "http://api.x.io/orders/42/items","type": "application/x-www-form-urlencoded","fields": [{ "name": "orderNumber", "type": "hidden", "value": "42" },{ "name": "productCode", "type": "text" },{ "name": "quantity", "type": "number" }
]}
],"links": [
{ "rel": [ "self" ], "href": "http://api.x.io/orders/42" },{ "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },{ "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
]}
l All contents Copyright © 2014, MuleSoft Inc.68
Strengths:
• Provides a more verbose spec
• Query templating
• Incorporates Actions
• Multi-format**
Siren
Weaknesses:
• Poor adoption
• Lacks documentation
• Work in progress
l All contents Copyright © 2014, MuleSoft Inc.70
CPHL
• Created by me in 2014
• Considered a “brain storming” document
• Multi-format with architectural consistency
• Action driven verses Resource driven
• Incorporates API definition specs (RAML/ Swagger)
• Allows for documentation and Code on Demand
• Not widely adopted
• Not considered stable
l All contents Copyright © 2014, MuleSoft Inc.71
CPHLProvides Strict Naming:• self: self provides a namespace for links to docs and code related to the exact call the client is
on• create: Create a new record via the POST method (equivalent to self::POST)• read: retrieve an item or collection via GET (equivalent to self::GET)• update: utilization of the put/ patch methods to update an item, or all items in a collection*
(self::PUT)• delete: deletes the item or the collection* (equivalent to self::DELETE)• search: the resource to perform a search on a collection• first: links to the first record in a collection• beginning: links to the first set of records in a paginated result• prev: links to the previous set of records in a paginated result• next: links to the next set of records in a paginated result• last: links to the last record of a paginated result• end: links to the last set of records in a paginated result• base: links back to the starting point of a hypermedia API
l All contents Copyright © 2014, MuleSoft Inc.72
CPHL{
"_definition": { "raml": "http://api.domain.com/docs/api/raml", "swagger": "http://api.domain.com/docs/api/swagger"
}, "_links": {
"update": { "title": "Edit User", "description": "edit the user", "href": "/api/resource", "methods": [
"put", "patch"
], "formats": {
"json": { "mimeType": "application/json", "schema": "http://api.domain.com/docs/api/editSchema.json"
}, "xml": {
"mimeType": "text/xml", "schema": "http://api.domain.com/docs/api/editSchema.xml"
} },
l All contents Copyright © 2014, MuleSoft Inc.73
CPHL
"docHref": "http://api.domain.com/docs/edit", "code": {
"php": { "href": "http://code.domain.com/phplib/edit.tgz", "md5": "0cc175b9c0f1b6a831c399e269772661", "recordSpecific": false
}, "java": {
"href": "http://code.domain.com/javalib/edit.tgz", "md5": "0cc175b9c0f1b6a831c399e269772661", "recordSpecific": false
}, "ruby": {
"href": "http://code.domain.com/rubylib/edit.tgz", "md5": "0cc175b9c0f1b6a831c399e269772661", "recordSpecific": false
} }
} }
}
l All contents Copyright © 2014, MuleSoft Inc.74
Strengths:
• Cross-platform (XML, JSON,
YAML) architectural consistency
• Incorporates documentation,
methods, and code on demand
• Provides strict name templating
for common actions
CPHL
Weaknesses:
• Poor adoption
• Not heavily tested/ supported
• Can become bloated/ overly
verbose
• Not stable – brain storming
document
l All contents Copyright © 2014, MuleSoft Inc.
YahapiUber Mason
CPHL
JSON API HAL
JSON-LD
Collection+JSON Siren
l All contents Copyright © 2014, MuleSoft Inc.
Remember, hypermedia needs to enable humans and machines to make dynamic decisions.
l All contents Copyright © 2014, MuleSoft Inc.
The problem is that we design APIs with the mindset that they are for developers… and that’s how we consume them.
l All contents Copyright © 2014, MuleSoft Inc.78
Common Hypermedia Mistakes
• Links are not self-describing – promote resources over actions failing to
provide the machine with enough information to dynamically proceed
with the next call (implement links like you would a webpage)
• Links are provided as a “documentation resource” instead of a state
representation for that object (forcing consumers to guess and
implement your business rules client side)
l All contents Copyright © 2014, MuleSoft Inc.
/users [get]
/users/password [post]
/users [post]
/base [get]
l All contents Copyright © 2014, MuleSoft Inc.81
Common Hypermedia Mistakes
• Hypermedia is used to replace documentation, not supplement it. Or
documentation is excluded from hypermedia responses.
• Hypermedia is used as an excuse to break backwards compatibility
(changing URIs at will)
• Hypermedia is used as a method to “prevent versioning.”
l All contents Copyright © 2014, MuleSoft Inc.82
Common Hypermedia Challenges
• Lack of knowledge within general LOB developer community regarding
how to consume Hypermedia Driven APIs
• Developers hard code links (see Stormpath’s API)
• Numerous calls are required for often simple operations, frustrating
developers (see RESTful API Call Chaining)
l All contents Copyright © 2014, MuleSoft Inc.83
Common Hypermedia Challenges Summed Up:
• Developers do not understand the benefits of
hypermedia
l All contents Copyright © 2014, MuleSoft Inc.84
Benefits of Hypermedia to Consumers:
• Explorable, self-guided API structure
• Client architecture is decoupled from business logic
• Ability to build in dynamic workflows
• Reduction in failed calls/ client forced errors
• Reduced maintenance need/ API less likely to be versioned
l All contents Copyright © 2014, MuleSoft Inc.
Disclaimer:Hypermedia specifications are changing very rapidly. Implement hypermedia, but be prepared to change/ provide more than one format.
l All contents Copyright © 2014, MuleSoft Inc.88
Sometimes I feel that “over-engineering” is this disease that is running wild in our industry and as architects we need to be on constant watch to quickly eliminate it whenever encountered.
- Drew Jaegle, Enterprise Architect