1. THE HYPERMEDIA API
Ben Longden / @blongden

2. WHO ARE YOU?
SOFTWARE ENGINEER & MANAGER
Inviqa, Session Digital, Sensio Labs UK

4. Twitter: blongden
GitHub: blongden
Email: ben@nocarrier.co.uk

5. ARCHITECTURAL STYLES

6. RPC
http://.../create_account.php?
email_addr=user@example.com&
passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&
user_name=CrunchAll

7. RICHARDSON MATURITY
LEVEL 0

8. THE SWAMP OF POX
PLAIN OLD XML
(OR JSON)

9. <user>
<emailaddr>user@example.com</emailaddr>
<username>CrunchAll</username>
</user>

10. WS-*
SOAP

11. RICHARDSON MATURITY
LEVEL 1

12. IDENTIFICATION OF
RESOURCES
PRETTY URLS

13. NO VERBS
FIND THE NOUNS

14. Users can create messages that are visible to other users who
follow them.

15. CRAFT URLS FOR YOUR
RESOURCES
http://.../users/{name}
http://.../messages/{id}

16. SUBSETS OF DATA
http://.../users/blongden/messages

17. HTTP AS A TUNNEL

18. METHODS
METADATA
PAYLOAD

19. HTTP IS SUCCESSFUL
AUTHENTICATION, CACHE, CONTENT
NEGOTIATION

20. RICHARDSON MATURITY
LEVEL 2
USE THE VERBS THAT HTTP PROVIDES
GET POST PUT DELETE
OPTIONS TRACE HEAD CONNECT PATCH

21. SAFE ACTIONS
HEAD & GET

22. IDEMPOTENT ACTIONS
HEAD, GET, PUT, DELETE
OPTIONS, TRACE

23. IDENTIFY STATES
LIST USERS, LIST A SINGLE USER
LIST MESSAGES, LIST A SINGLE MESSAGE
CREATE/UPDATE/DELETE A USER
FOLLOW/UNFOLLOW A USER

24. GET /users/blongden/messages HTTP/1.1
Host: example.com

25. POST /users/blongden/messages HTTP/1.1
Host: example.com

26. PUT /users/blongden/messages/1 HTTP/1.1
Host: example.com

27. DELETE /users/blongden/messages/1 HTTP/1.1
Host: example.com

28. RICHARDSON MATURITY
MODEL LEVEL 3
HYPERMEDIA

29. HYPERMEDIA
Hypermedia 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.

30. HYPERMEDIA
AFFORDANCES

31. [LE] EMBEDDED LINKS
<img src='http://example.com/logo' />

32. [LO] OUTBOUND LINKS
<a href='http://example.com/search' title='view search page'>
Search
</a>

33. [LT] TEMPLATED QUERIES
<form method='get'>...</form>

34. [LN] NON-IDEMPOTENT
UPDATES
<form method='post'>...</form>

35. [LI] IDEMPOTENT
UPDATES
SUPPORT FOR PUT AND DELETE

36. REGISTERED MEDIA TYPES

37. HAL
HYPERTEXT APPLICATION LANGUAGE

38. "_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
]}

39. <?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@j
ones.com>"/>
<total>30</total>
<currency>USD</currency>
</resource>
</resource>

40. <?php
$hal = new NocarrierHal('/orders');
$hal->addLink('next', '/orders?page=2');
$hal->addLink('search', '/orders?id={order_id}');
$resource = new NocarrierHal(
'/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();

41. LINK RELATIONS

42. SHORT SYNTAX
"STYLESHEET", "PROFILE"

43. MICROFORMATS
registered link relations

44. IANA
registered link relations

45. CUSTOM LINK RELATIONS
http://.../rels/message

46. DESIGNING A
HYPERMEDIA TYPE

47. XML OR JSON?
HTML? YAML?

48. JSON
UBIQUITOUS AND EASY TO PARSE
RIGID STRUCTURE

49. XML
UBIQUITOUS BUT HARDER TO PARSE
EVOLVABLE

50. {
"name": "Ben",
"phone": "07777000000"
}

51. {
"name": "Ben",
"phone": [ "07777000000", "07777000001" ]
}

52. <?xml version="1.0"?>
<contact>
<name>Ben</name>
<phone>07777000000</phone>
</contact>

53. <?xml version="1.0"?>
<contact>
<name>Ben</name>
<phone>07777000000</phone>
<phone>07777000001</phone>
</contact>

54. CONSIDER H-FACTORS
DO YOU NEED TO EXTEND AN EXISTING
FORMAT?

55. WHY USE A REGISTERED
TYPE?

56. EXISTING TOOLS

57. INTEROPERABILITY

58. THE 'CHATTY API'
PROBLEM

59. ZOOM
THE HYPERTEXT CACHE PATTERN

60. http://.../users/blongden?zoom=messages
{
"_links": {
"self": { href: "http://.../users/blongden" },
"messages": { href: "http://.../users/blongden/messages" }
}
"_embedded": {
"messages": { ... }
}
}

61. COMMON INTERFACE

62. THANK YOU.
http://joind.in/8048