Building Hypermedia API's - YOW! Night - March 2013

YOW!
Nights
March 2013

Kevin O’Neill
CTO PlayUp

@kevinoneill

Kevin O’Neill - CTO PlayUp - @kevinoneill YOW! Nights - March 2013

Roadmap
• ReST and Hypermedia

• An example of a Hypermedia driven service

• Tips & Trips


A jumping off point


Opinionated


Real


ReST & Hypermedia


Representational State Transfer (ReST) is a
style of software architecture for distributed
hypermedia systems such as the
World Wide Web


ReST


ReST is not a
meaningful term


One URL ≠ ReST


One URL ≠ ReST

http://example.com/system?action=getUser&uid=3

http://example.com/system?action=mkUser&name=…

http://example.com/system?action=rmUser&uid=3


Resources = ReST ?


Resources = ReST ?

http://example.com/users/3

http://example.com/users/<uid>

http://example.com/users/<uid>/friends


HTTP Verbs = ReST ?


HTTP Verbs = ReST ?

POST
http://example.com/users

GET

PUT

DELETE


What is ReST really?


"ReST is software design on the scale of
decades: every detail is intended to promote
software longevity and independent evolution.
Many of the constraints are directly opposed
to short-term efficiency. Unfortunately, people
are fairly good at short-term design, and
usually awful at long-term design."

Roy Fielding


The constraints of
ReST


Client Server


Stateless Server


Cacheable


Uniform Interface


Layered System


Code-On-Demand
(optional)


Identification of
Resources


Manipulation of
resources through
representations


Self-descriptive
messages


Hypermedia as the
engine of application
state


“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?”

Roy T. Fielding


A Hypermedia driven
service


PlayUp Pass


Getting the Price
TMS 2 Get Tile

1 Get Section 4 Section

3 Priced Tile
7:20 PM

7 Get Price

Content
App
Provider
Store
($)
8$

5 6

Ticket
Service


Products
":type":
"application/vnd.playup.ticketing.product+json",

"product":
{

"detail":
{

":type":
"application/vnd.playup.encrypted+json",

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":
"application/vnd.playup.ticketing.product.detail+json"

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

"preview":
{

":href":
"http://april.ticket-‐provider.playupdev.com/content/82/preview?
token={token:ticketing_sample_provider}",

":type":
"application/vnd.playup.stream.story+json"

},

"provider":
"ticketing_sample_provider"
},

"offer":
{

":href":
"http://april.ticket.playupdev.com/ticket?
provider=ticketing_sample_provider&token={token:ticket_service}",

":options":
[

"POST"

]

":acceptable_types":
[

"application/vnd.playup.encrypted+json;embedded="application/
vnd.playup.ticketing.product.details+json";for="ticket_service""

],

}


Products
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

":type":
"application/vnd.playup.ticketing.product+json"

"preview":
{

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Preview
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"preview":
{

"type":

}

":href":
"http://april.ticket-‐provider.playupdev.com/content/

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

82/preview?token={token:ticketing_sample_provider}",

"name":
"F1
GP
Insider",

"preview":
{

":type":

":href":
},


":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Preview
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

":type":

"preview":
{

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Accept Header


Accept Header

Accept

application/vnd.playup.stream.story+json,*/*


Preview
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

":href":
"http://april.ticket-‐provider.playupdev.com/content/

"name":
"F1
GP
Insider",

"preview":
{
82/preview?token={token:ticketing_sample_provider}"

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


URI Parameterization


":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

{token:ticketing_sample_provider}

"preview":
{

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


http://april.ticket-‐provider.playupdev.com/content/82/preview?
token=ABBr0dVOGRdPpF%2BAqll9sJNJAICWEHK
%2BnTngDMzBI5IiABmlstT3RjwIBGkJpUCX3lchMQF3OrGoYyiYHh8zAbc7m
%2FhsttbKyBBa%2BiX5hSApeBi1erBw7oJH9LBmk
%2B1pfL2zApBDxCZZpJCkT5hScK1Z2g3%2BDhqkrQJTs3PQumbbC9bXJRnENksQhs
b
%2BNJuFrJ47sAGQBPPXyN0hy40i3J6LcwGMUSFIaR5kIAw3%2BiYyiKgC35rmZzvM
YGEeV%2F08YR1ih47aKct5%2Fk0CTbzR06qxi1W11fR3pSMBn3HxqgYPjjMdgsa
%2B5PiLv102eTk7kXc4Aqz1VDN2ogqu3qDbzebxdp6OOhnoSKa3jebrV9MOH6IgBR
KYfiujq7MNle1xV1LwUQlm3T4BagclibIqOq%2FS1psWo0oZfU1DQW5h2AX
%2BLrvF%2BGfgFRiHvaOWBUuq5esY0yqENyjD3Yu8WGq15MTqI36oK5S6hUy
%2F0gAlB0rFMU
%2BSX4WbuX64yjlKVWV5wr7E3FmaxT7yr98pGq04zKrJv2tn4rpUtcRoc8LrYiK2B
doQplYATGBCDgv68p%2FTiislPJv0%2B4hqhO5oAIv7fMa81uy
%2F5WMcOjzmmsOgJzua0%2B%2FarXna9I3d0djqJ9fTDSQkM6icwz5u2P
%2Btulzwq8UHEgYEFYFGUKyk
%2BEXUgre7nttltajpLL3fRqGfrUqyI1NNM1dqGjeDN4zL0YA8KujtSoSWcA%3D
%3D


Offers
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

"preview":
{

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Offers
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

":href":

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

provider=ticketing_sample_provider&token={token:ticket_service}

"preview":
{
"

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Offers
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

":options":
[

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

Text

"name":
"F1
GP
Insider",

"POST"

"preview":
{

":href":

]

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

],

[


]

}


Offers
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

[

"type":

}

"application/vnd.playup.encrypted+json

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

;embedded=

"name":
"F1
GP
Insider",

"preview":
{

"application/vnd.playup.ticketing.product.details+json"

":href":

;for="ticket_service""

":type":
]

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Media Types


Media Types
describe a domain
specific protocol


application/json


Media Type Explosion


Media Types
":type":

"product":
{

"detail":
{

":type":

"aes256-‐cbc":
{

"data":
"
…
",

"iv":
"
…
",

"key":
"
…
",

"signature":
"
…
",

"type":

}

},

"id":
"82699e9b-‐b147-‐46b4-‐a90c-‐24316071b6e9",

"name":
"F1
GP
Insider",

"preview":
{

":href":

":type":

},

"provider":
},

"offer":
{

":href":

":options":
[

"POST"

]

[


],

}


Media Types

application/vnd.playup.encrypted+json;embedded=
"application/vnd.playup.ticketing.product.details
+json";for="ticket_service"


Something to consider


Format vs Type

application/vnd.playup.stream+json


Format vs Type

application/vnd.playup.stream+mp


Format vs Type

application/vnd.playup.stream;format=”json”


So now we post


Offer
{

":type":
"application/vnd.playup.ticketing.offer+json",

"content":
{

"expiration":
"2015-‐03-‐13
01:12:44
+0000",

"store-‐product":
[

{

"product":
"com.playup.content.pricing.tier1",

"vendor":
"appstore"

}

]

},

"verification":
{

"key":
"…",

"link":
{

[

vnd.playup.ticketing.receipt+json";for="ticket_service""

],

":href":
"http://april.ticket.playupdev.com/receipt?token={token:ticket_service}",

":options":
[

"POST"

]

}

}
}


Offer
{

":type":

"content":
{

"expiration":
"2015-‐03-‐13
01:12:44
+0000",

"content":
{

"store-‐product":
[

{

"expiration":
"2015-‐03-‐13
01:12:44
+0000",

"product":

"store-‐product":
[

"vendor":
"appstore"

}

{

]

},

"product":

"verification":
{

"vendor":
"appstore"

"key":
"…",

"link":
{

}

[


]
vnd.playup.ticketing.receipt+json";for="ticket_service""

],

}

":href":

":options":
[

"POST"

]

}

}
}


Offer
{

":type":

"content":
{

"expiration":
"2015-‐03-‐13
01:12:44
+0000",

"store-‐product":
[

{
"link":
{

"product":

":href":
"http://april.ticket.playupdev.com/receipt…",

"vendor":
"appstore"

}

":options":
[
"POST"
],

]

},

[

"verification":
{

"application/vnd.playup.encrypted+json;…"

"key":
"…",

"link":
{

]

[

} vnd.playup.ticketing.receipt+json";for="ticket_service""

],

":href":

":options":
[

"POST"

]

}

}
}


Tips & Trips


API Versioning


Versioning

X-‐PlayUp-‐API-‐Version

3


Don’t Do It


Server Decides

User-‐Agent

PlayUp%20Pass/3.5.5233
CFNetwork/609.1.4

Darwin/13.0.0


Client Decides

"link":
{

":representations":
[

{

"href":
"http://twinstapics.playupdev.com/photos/86/stream
…"
,

"type":
"application/vnd.playup.stream+json"

},

{

"href":
"http://twinstapics.playupdev.com/photos/86/section
…"

,

"type":
"text/html"

}

],

":self":
…",

":type":
"text/html"
},


Client Decides

"link":
{

":representations":
[

{

"href":
"http://twinstapics.playupdev.com/photos/86/stream
…"
,

"type":
"application/vnd.playup.stream+json"

},

{

"href":
…"

,

"type":
"text/html"

}

],

":href":
…",

":type":
"text/html"
},


Client vs Server


Document Evolution


The client should
ignore what it doesn’t
understand


Don’t add or remove
mandatory fields


New Media Type


"Realtime" Updates


XMPP


Polling


Leverage
Infrastructure


Dynamic Scaling


Cache Headers

ETag
"9461cf5ecc0f4df6e880ce76479aba90"

Cache-‐Control
max-‐age=15,
public

Vary
Accept-‐Language


Cache Headers

ETag
"9461cf5ecc0f4df6e880ce76479aba90"

Cache-‐Control

max-‐age=15,
public
Cache-‐Control
max-‐age=15,
public

Vary
Accept-‐Language


Other Choices


Tools


Charles


Fiddler


Link Conditioner


Wireshark


Wireshark

rvictl
-‐s
<device
UDID>

/def/bpf*


Questions?
Kevin O’Neill
CTO - PlayUp
@kevinoneill
kevin@playup.com


Building Hypermedia API's - YOW! Night - March 2013

Recomendados

Recomendados

Más contenido relacionado

Destacado

Destacado (10)

Similar a Building Hypermedia API's - YOW! Night - March 2013

Similar a Building Hypermedia API's - YOW! Night - March 2013 (20)

Último

Último (20)

Building Hypermedia API's - YOW! Night - March 2013