This document provides a practical guide to building hypermedia APIs. It discusses hypermedia basics like resources not equating to models and using HTTP methods and status codes. It presents a sample HAL response and describes building server-side controllers, models, and serializers. On the client-side, it discusses using Faraday and integrating with Rails. It lists problems like lack of ids and speed issues. Resources provided include guides on creating hypermedia clients and abusing ActiveModel::Serializers for HAL representation. Useful testing gems are also listed.

1. A Practical Guide to
Hypermedia APIs
Eric Oestrich
@ericoestrich
@smartlogicsolutions

2. woofound.com

4. That was this project
Prepare yourself

5. Please note that this has been
heavily stripped down
Don't want to give everything away

6. But first
Hypermedia Basics

7. Resources != Models

8. HTTP is your friend
methods and status codes

9. Client knows only one
URL
"/"

10. Media types
HAL

11. Sample HAL Response
{
"status": "Processing",
"_embedded": {
"items": [
{
"name": "Book",
"_links":{ "self": { "href" => "http://example.com/items/1" } }
}
]
},
"_links": {
"self" => { "href" => "http://example.com/orders/1" }
}
}

12. Server

13. Controllers
● Use respond_to and respond_with

14. Models
● Doesn't have to be a subclass of
ActiveRecord::Base

15. Serializers
● Disable root
● Links
● Embedded resources
● Changing serializer representations

16. Client

17. Basics
● Uses Faraday
● Basic auth over SSL

18. Resources
● Data only
● Convenience methods
● Links

19. Loaders
● Pull data down from the API
● Only GETs

20. Services
● Very similar to Loaders
● Push data back up

21. Integrating with Rails

22. Problems
● There are no ids
● Speed

23. Resources
● Creating a Hypermedia Client
○ http://blog.oestrich.org/2012/12/creating-a-
hypermedia-client/
● ActiveModel::Serializers
○ https://github.com/rails-api/active_model_serializers
● Abusing ActiveModel::Serializers for HAL
○ http://blog.oestrich.org/2012/10/abusing-active-
model-serializers-for-hal/
● httpstatus.es

24. Useful gems for apis
● rspec_api_documentation
● raddocs
● letter
● json_spec
● vcr
● webmock
● cane

25. Hobostove
Campfire for the command line
https://github.com/oestrich/hobostove