1. A Practical Guide to
Hypermedia APIs
Eric Oestrich
Philly.rb
2013-03-12

2. Eric Oestrich
SmartLogic Solutions
http://www.smartlogicsolutions.com
@ericoestrich
github.com/oestrich

3. A Brief Intro to the
Domain

4. NerdWord
github.com/smartlogic/nerdword
github.com/smartlogic/nerdword-api
github.com/smartlogic/nerdword-client-ruby

5. Definitely Not Scrabble

6. Resources

7. Users
Actions:
Register
Basic Auth

8. Games
Users that are playing on a shared
board
Actions:
Create
List
View
Play Move

9. Move
Set of tiles to be played at a location

10. Turns
Actions:
List
View

11. See It In Action
https://github.com/smartlogic/nerdword-api/
blob/master/script/client.rb

12. Hypermedia Basics

13. Client Knows Only One
URL
"/"

14. Media Types
HAL

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

16. Server Side

17. Controllers
Rails::Api

18. Models
Do not have to be ActiveRecord::Base

19. Resources
Should not be all of your models exported

20. Serializers
Disable root
Links
Embedded resources
Changing serializer representations

21. Client Side

22. Basics
Faraday
Basic auth over SSL
Handle link traversal

23. Resources
Data only
Convenience methods
Links

24. Loaders
Pull down data
Only GETs

25. Services
Very similar to Loaders
Push data back up
Perform actions
POST, PUT

26. Helpful 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

27. Useful Gems for APIs
rspec_api_documentation
raddocs
letter
json_spec
vcr
webmock
cane

28. Questions?
http://www.smartlogicsolutions.com
http://www.twitter.com/smartlogic
http://www.github.com/smartlogic
http://www.facebook.com/smartlogic