A Practical Guide to Hypermedia APIs

Eric Oestrich

Philly.rb2013-03-12

http://www.smartlogicsolutions.com

@ericoestrich

github.com/oestrich

Eric OestrichSmartLogic Solutions

A Brief Intro to the Domain

NerdWordgithub.com/smartlogic/nerdword

github.com/smartlogic/nerdword-apigithub.com/smartlogic/nerdword-client-ruby

Definitely Not Scrabble

Resources

UsersActions:Register

Basic Auth

GamesUsers that are playing on a shared

board

Actions:Create

ListView

Play Move

MoveSet of tiles to be played at a location

TurnsActions:

ListView

See It In Actionhttps://github.com/smartlogic/nerdword-api/

blob/master/script/client.rb

Hypermedia Basics

Client Knows Only One URL

"/"

Media TypesHAL

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

Server Side

ControllersRails::Api

ModelsDo not have to be ActiveRecord::Base

ResourcesShould not be all of your models exported

SerializersDisable root

LinksEmbedded resources

Changing serializer representations

Client Side

BasicsFaraday

Basic auth over SSLHandle link traversal

ResourcesData only

Convenience methodsLinks

LoadersPull down data

Only GETs

ServicesVery similar to Loaders

Push data back upPerform actions

POST, PUT

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

Useful Gems for APIsrspec_api_documentation

raddocsletter

json_specvcr

webmockcane

Questions?

http://www.smartlogicsolutions.com

http://www.twitter.com/smartlogic

http://www.github.com/smartlogic http://www.facebook.com/smartlogic