The hypermedia api
Transcript of The hypermedia api
WHO ARE YOU?SOFTWARE ENGINEER & MANAGER
Inviqa, Session Digital, Sensio Labs UK
ARCHITECTURAL STYLES
RPChttp://.../create_account.php?
passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&
user_name=CrunchAll
RICHARDSON MATURITYLEVEL 0
THE SWAMP OF POXPLAIN OLD XML
(OR JSON)
<user> <emailaddr>[email protected]</emailaddr> <username>CrunchAll</username></user>
WS-*SOAP
RICHARDSON MATURITYLEVEL 1
IDENTIFICATION OFRESOURCES
PRETTY URLS
NO VERBSFIND THE NOUNS
Users can create messages that are visible to other users who
follow them.
CRAFT URLS FOR YOURRESOURCES
http://.../users/{name}
http://.../messages/{id}
SUBSETS OF DATAhttp://.../users/blongden/messages
HTTP AS A TUNNEL
METHODSMETADATAPAYLOAD
HTTP IS SUCCESSFULAUTHENTICATION, CACHE, CONTENT
NEGOTIATION
RICHARDSON MATURITYLEVEL 2
USE THE VERBS THAT HTTP PROVIDESGET POST PUT DELETE
OPTIONS TRACE HEAD CONNECT PATCH
SAFE ACTIONSHEAD & GET
IDEMPOTENT ACTIONSHEAD, GET, PUT, DELETE
OPTIONS, TRACE
IDENTIFY STATESLIST USERS, LIST A SINGLE USER
LIST MESSAGES, LIST A SINGLE MESSAGECREATE/UPDATE/DELETE A USER
FOLLOW/UNFOLLOW A USER
GET /users/blongden/messages HTTP/1.1Host: example.com
POST /users/blongden/messages HTTP/1.1Host: example.com
PUT /users/blongden/messages/1 HTTP/1.1Host: example.com
DELETE /users/blongden/messages/1 HTTP/1.1Host: example.com
RICHARDSON MATURITYMODEL LEVEL 3
HYPERMEDIA
HYPERMEDIAHypermedia is used as a logical extension of the term
hypertext in which graphics, audio, video, plain text and
hyperlinks intertwine to create a generally non-linear
medium of information.
HYPERMEDIAAFFORDANCES
[LE] EMBEDDED LINKS<img src='http://example.com/logo' />
[LO] OUTBOUND LINKS<a href='http://example.com/search' title='view search page'> Search</a>
[LT] TEMPLATED QUERIES<form method='get'>...</form>
[LN] NON-IDEMPOTENTUPDATES
<form method='post'>...</form>
[LI] IDEMPOTENTUPDATES
SUPPORT FOR PUT AND DELETE
REGISTERED MEDIA TYPES
HALHYPERTEXT APPLICATION LANGUAGE
"_links": { "next": { "href": "/orders?page=2" }, "self": { "href": "/orders" }},"_embedded": { "order": [ "_links": { "customer": { "href": "/customer/bob", "title": "Bob Jones <[email protected]>" }, "self": { "href": "/orders/123" } }, "currency": "USD", "total": 30]}
<?xml version="1.0"?><resource href="/orders"> <link rel="next" href="/orders?page=2"/> <link rel="search" href="/orders?id={order_id}"/> <resource rel="order" href="/orders/123"> <link rel="customer" href="/customer/bob" title="Bob Jones <[email protected]>"/> <total>30</total> <currency>USD</currency> </resource></resource>
<?php$hal = new \Nocarrier\Hal('/orders');$hal->addLink('next', '/orders?page=2');$hal->addLink('search', '/orders?id={order_id}');
$resource = new \Nocarrier\Hal( '/orders/123', array( 'total' => 30.00, 'currency' => 'GBP', ));
$resource->addLink('customer', '/customer/bob', 'Bob Jones <[email protected]>');$hal->addResource('order', $resource);echo $hal->asXml();echo $hal->asJson();
LINK RELATIONS
SHORT SYNTAX"STYLESHEET", "PROFILE"
MICROFORMATSregistered link relations
IANAregistered link relations
CUSTOM LINK RELATIONShttp://.../rels/message
DESIGNING AHYPERMEDIA TYPE
XML OR JSON?HTML? YAML?
JSONUBIQUITOUS AND EASY TO PARSE
RIGID STRUCTURE
XMLUBIQUITOUS BUT HARDER TO PARSE
EVOLVABLE
{ "name": "Ben", "phone": "07777000000"}
{ "name": "Ben", "phone": [ "07777000000", "07777000001" ]}
<?xml version="1.0"?><contact> <name>Ben</name> <phone>07777000000</phone></contact>
<?xml version="1.0"?><contact> <name>Ben</name> <phone>07777000000</phone> <phone>07777000001</phone></contact>
CONSIDER H-FACTORSDO YOU NEED TO EXTEND AN EXISTING
FORMAT?
WHY USE A REGISTEREDTYPE?
INTEROPERABILITY
THE 'CHATTY API'PROBLEM
ZOOMTHE HYPERTEXT CACHE PATTERN
http://.../users/blongden?zoom=messages
{ "_links": { "self": { href: "http://.../users/blongden" }, "messages": { href: "http://.../users/blongden/messages" } } "_embedded": { "messages": { ... } }}
COMMON INTERFACE
THANK YOU.http://joind.in/8048