Internal Tech Talk about REST and Hypermedia

1. Representational
State
Transfer
Rodrigo D. A. Senra
EMC BRDC TechTalk

2. Overview
• Roy Fielding’s Vision
• ReST = URI + HTTP + Hypermedia
• API Design
• Success Stories
• Q & A

3. ReST for a minute
What: Representational State Transfer (REST) architectural style
Who: Roy Thomas Fielding
When: 2000
Where: Chapter 5, Ph.D. dissertation: “Architectural Styles and the Design of Network-based Software Architectures”
Why: need for blueprints to guide the design and development of the architecture for the modern Web
• scalable component interactions
• general and uniform interfaces
• self-descriptive representations
• independent deployable components
• reduced interaction latency
• enforced security
• able to encapsulate legacy systems
How: HTTP + URI + (Client Pull - Resolver - [Cache] - Stateless [Tunnel] - Server ) = ULCODC$SS

4. Patterns
• (Uniform) Pipe and Filters
• Replicated Repository
• Cache$
• Client Server
• Layered Systems
• Remote Session
• Remote Data Access
• Mobile Code Styles
• Virtual Machine
• Remote Evaluation
• Code on Demand
• Mobile Agent
• Event-based Integration
• (Brokered) Distributed Objects

5. from Roy Fielding’s Dissertation

6. Evaluation Criteria
•modifiability
•evolvability
•extensibility
•customizability
•configurability
•reusability
•simplicity
•scalability
•portability
•reliability
•visibility

7. from Roy Fielding’s Dissertation

8. Connectors != Components
from A Guide to REST and API Design
Solve problems
in unique ways
public andstandardized

9. from Roy Fielding’s Dissertation
from A Guide to REST and API Design

10. Data Structure
Data Element Examples
resource conceptual target of a hypertext reference
resource identifier URI (URN or URL)
resource metadata source link, alternates, vary, …
representation HTML, XML, JSON, JPG,…
representation metadata media-type, last-modified,…
control data if-modified-since, cache-control,…

12. $ curl -i -X HEAD http://stackoverflow.com/questions/4913343/what-is-the-difference-between-uri-url-and-urn
HTTP/1.1 200 OK
Cache-Control: public, no-cache="Set-Cookie", max-age=60
Content-Length: 92646
Content-Type: text/html; charset=utf-8
Expires: Thu, 12 Mar 2015 23:42:26 GMT
Last-Modified: Thu, 12 Mar 2015 23:41:26 GMT
Vary: *
X-Frame-Options: SAMEORIGIN
X-Request-Guid: 8f94e452-513b-43fb-958d-5de2aa67a557
Set-Cookie: prov=aa08df12-afe7-4073-928f-a09504693cc5; domain=.stackoverflow.com;

14. 7 Steps to API design
1.List all data elements clients might need
2.Draw state diagrams (actions)
3.Reconcile Magic Strings (schema.org, DC, FOAF,…)
4.Select Media-types (html, xml, json, csv, hdf5,…)
5.Create a semantic profile (WSDL, WADL, APP, RAML,
Swagger,/ALPS,Json-LD, Json-Schema Hydra)
6. Write the code
7.Publish the API
from A Web API Design Methodology - Mike Amundsen

15. Some RESTful APIs
• Amazon S3
• Google DoubleClick Ad Exchange Buyer
• Google YouTube
• Twitter
• Twilio Voice and SMS
• Netflix API (2014/11)
• Facebook Graph
• EMC Isilon OneFS

16. Isilon REST API Example
The following request creates an access point named 'accesspoint1' on the namespace.
PUT /namespace/accesspoint1 HTTP/1.1
Host my_cluster:8080
Date: Fri, 15 Mar 2013 21:51:50 GMT
Content-Type: text/xml
{
"path": “/ifs/home/"
}
Example response
HTTP/1.1 200 OK
Date: Fri, 15 Mar 2013 21:51:50 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x
Allow: DELETE, GET, HEAD, POST, PUT, OPTIONS
x-isi-ifs-spec-version: 1.0
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=15, max=335
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

17. Facebook Graph API - https://developers.facebook.com/tools/explorer
The Graph API is the primary way to get data in and out of Facebook's
platform. It's a low-level HTTP-based API that you can use to query
data, post new stories, manage ads, upload photos and a variety of
other tasks that an app might need to do

18. Brainiak is …
• 100% Python
•API RESTful
• Hypermedia (HATEOAS)
• Json-schema ☜☞ RDF

19. Architecture

20. Legacy Virtuosos
Solr
Bus
Replicator
Authentication & Authorization
Backstage
Eureka VoceDaNota A-Z Sitemaps CMAaS
Brainiak
ElasticSearch
Architecture

21. Query SPARQL
select ?id ?nome
from esportes:
where {
?id rdf:type esportes:Equipe .
?id rdfs:label ?nome .
}

22. /esportes/Equipe
Brainiak API
GET

23. Response
{
"items": [
{
"title": "Atlético-MG",
"@id": "http://semantica.globo.com/esportes/equipe/282",
"class_prefix": "esportes",
"resource_id": "282"
},
{
"title": "Bahia de Feira",
"@id": "http://semantica.globo.com/esportes/equipe/2590",
"class_prefix": "esportes",
"resource_id": "2590"
}[
],
"@id": "esportes:Equipe"
}

24. Schema
{
"links": [
{
"href": "/esportes/Equipe/_schema?class_prefix=http://semantica.globo.com/esportes/",
"method": "GET",
"rel": "class"
},
{
"href": "/esportes/Equipe?class_prefix=http://semantica.globo.com/esportes/",
"method": "POST",
"rel": "create",
"schema": {"$ref": "{+_base_url}"}
},
{
"href": "/_/_/_?instance_uri={value}",
"method": "GET",
"rel": "relatedInstance"
},
…
/esportes/Equipe/_schema

25. Hyper-map

28. Business Perspective
from eMag Web APIs from Start to Finish
"As a result of Data Enabled Disruption, many
of Amazon’s former competitors are now dead.
By utilizing APIs at all points of the data
lifecycle, Amazon is able to continuously
improve the accuracy, applicability, and
accessibility of its data. "

29. Jeff Bezos
As Yegge's recalls that one day Jeff Bezos issued a mandate, sometime back around
2002 (give or take a year):
All teams will henceforth expose their data and functionality through service
interfaces.
Teams must communicate with each other through these interfaces.
There will be no other form of inter-process communication allowed: no direct linking,
no direct reads of another team’s data store, no shared-memory model, no back-doors
whatsoever.
The only communication allowed is via service interface calls over the network.
It doesn’t matter what technology they use.
All service interfaces, without exception, must be designed from the ground up to be
externalizable. That is to say, the team must plan and design to be able to expose the
interface to developers in the outside world. No exceptions.
Anyone who doesn’t do this will be fired. Thank you; have a nice day!
from http://apievangelist.com/2012/01/12/the-secret-to-amazons-success-internal-apis/

30. References
REST API Design Rulebook
Mark Masse (2011)
RESTful Web APIs
Leonard Richardson and Mike Amundsen
(2013)
REST APIs must be hypertext- driven
Roy T. Fielding: Untangled (2008)
RESTful Web Services
Leonard Richardson and Sam Ruby (2008)
HTTP Developer’s Handbook
Chris Shiflett (2003)
RESTful Web Services Cookbook
Subbu Allamaraju (2010)
Building Hypermedia APIs with HTML5 and Node
Mike Amundsen (2011)

31. Thank you.
Rodrigo Dias Arruda Senra
rodrigo.senra@emc.com
http://rodrigo.senra.nom.br
@rodsenra