An introduction to Hypermedia APIs from software developer Eric Oestrich.

1. Introduction to
Hypermedia APIs
Eric Oestrich
@ericoestrich
oestri.ch
smartlogicsolutions.com

2. What is a Hypermedia
API?

3. REST
REpresentational State Transfer

4. Relies Heavily on HTTP
● Methods and URI
● Media Types
● Client Server

5. Relies Heavily on HTTP
(Cont)
● Stateless
● Caching
● Uniform Interface (HATEOAS)

6. Methods and URIs

7. Five Routes
GET /orders
POST /orders
GET /orders/:id
PUT /orders/:id
DELETE /orders/:id

8. GET /orders
List of orders

9. POST /orders
Create an order

10. GET /orders/:id
View a single order

11. PUT /orders/:id
Replace or create an order

12. DELETE /orders/:id
Delete an order

13. A bit about HTTP Verbs

14. GET
Retrieve a resource

15. POST
Most generic

16. PUT
Replace or Create
Not partial

17. DELETE
Delete a resource

18. PATCH
Update partially
Must be a diff

19. Media Types

20. Formats
● JSON
● XML
● XHTML

21. Setting the Media Type
● Accept Headers
● Rails way - .:format

22. Representational based
Models != Representations

23. Uniform Interface

24. Uniform Interface
● Identification of resources
● Manipulation of resources via
representations
● Self descriptive messages
● Hypermedia as the engine of application
state

25. Identification of
resources

26. Manipulation of resources
via representations

27. Self descriptive
messages
Statelessness

28. Hypermedia as the engine
of application state
HATEOAS

29. Clients should not know
how to build routes

30. Enter HAL
JSON cannot describe a link

31. HAL is a media type for
defining links in JSON
application/hal+json

32. The Goal
GET /

33. Great, now I know what a
Hypermedia API is.

34. How do I make one?

35. Rails + Lots of Gems
Also monkey patching

36. Gems
● ActiveModel::Serializer
● RspecApiDocumentation
● Raddocs
● A few other handy ones

37. $ rails new hypermedia_api --skip-test-unit

38. $ vim Gemfile
gem 'raddocs'
gem 'active_model_serializers'

39. $ vim Gemfile
group :test, :development do
gem 'rspec-rails'
gem 'rspec_api_documentation'
end

40. Get rspec set up

41. Create our first
acceptance test

42. Generate models, index
action, serializers

43. Show

44. Create

45. Update

46. Delete

47. Setup HAL
Let the monkey patching begin

48. We're missing
something...

49. $ curl http://localhost:3000/
""

50. Root Resource

51. Questions?
Eric Oestrich
@ericoestrich
oestri.ch
smartlogicsolutions.com