intro to hypermedia apis
DESCRIPTION
An introduction to Hypermedia APIs from software developer Eric Oestrich.TRANSCRIPT
Introduction to Hypermedia APIs
Eric Oestrich@ericoestrich
oestri.chsmartlogicsolutions.com
What is a Hypermedia API?
RESTREpresentational State Transfer
Relies Heavily on HTTP● Methods and URI● Media Types● Client Server
Relies Heavily on HTTP (Cont)
● Stateless● Caching● Uniform Interface (HATEOAS)
Methods and URIs
Five RoutesGET /ordersPOST /ordersGET /orders/:idPUT /orders/:idDELETE /orders/:id
GET /ordersList of orders
POST /ordersCreate an order
GET /orders/:idView a single order
PUT /orders/:idReplace or create an order
DELETE /orders/:idDelete an order
A bit about HTTP Verbs
GETRetrieve a resource
POSTMost generic
PUTReplace or Create
Not partial
DELETEDelete a resource
PATCHUpdate partiallyMust be a diff
Media Types
Formats● JSON● XML● XHTML
Setting the Media Type● Accept Headers● Rails way - .:format
Representational basedModels != Representations
Uniform Interface
Uniform Interface● Identification of resources● Manipulation of resources via
representations● Self descriptive messages● Hypermedia as the engine of application
state
Identification of resources
Manipulation of resources via representations
Self descriptive messages
Statelessness
Hypermedia as the engine of application state
HATEOAS
Clients should not know how to build routes
Enter HALJSON cannot describe a link
HAL is a media type for defining links in JSON
application/hal+json
The GoalGET /
Great, now I know what a Hypermedia API is.
How do I make one?
Rails + Lots of GemsAlso monkey patching
Gems● ActiveModel::Serializer● RspecApiDocumentation● Raddocs● A few other handy ones
$ rails new hypermedia_api --skip-test-unit
$ vim Gemfilegem 'raddocs'gem 'active_model_serializers'
$ vim Gemfilegroup :test, :development do gem 'rspec-rails' gem 'rspec_api_documentation'end
Get rspec set up
Create our first acceptance test
Generate models, index action, serializers
Show
Create
Update
Delete
Setup HALLet the monkey patching begin
We're missing something...
$ curl http://localhost:3000/""
Root Resource
Questions?Eric Oestrich@ericoestrich
oestri.chsmartlogicsolutions.com