the hypermedia api

THE HYPERMEDIA API / Ben Longden @blongden

WHO ARE YOU?SOFTWARE ENGINEER & MANAGER

Inviqa, Session Digital, Sensio Labs UK

Twitter: blongden

GitHub: blongden

Email: ben@nocarrier.co.uk

ARCHITECTURAL STYLES

RPChttp://.../create_account.php?

email_addr=user@example.com&

passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&

user_name=CrunchAll

RICHARDSON MATURITYLEVEL 0

THE SWAMP OF POXPLAIN OLD XML

(OR JSON)

<user> <emailaddr>user@example.com</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 <bob@jones.com>" }, "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 <bob@jones.com>"/> <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 <bob@jones.com>');$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?

EXISTING TOOLS

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