API REST for beginners...

...or why I should care about building an understandable API

POST /hello-world

Javier Lafora(@eLafo)

A small walk through history

Web of documents

Widgets

Web scraping

SOAP

Mashups

http://cartodb.github.io/lisbon-2014/#/2/24.7/-7.0/0

Internet of Things

Internet of everything

Same app on multiple devices

http://www.mediabistro.com/alltwitter/api-billionaires-club_b11424

http://www.programmableweb.com/news/9000-apis-mobile-gets-serious/2013/04/30

http://apiux.com/2013/05/29/api-hierarchy-needs/

https://www.lordabbett.com/content/lordabbett/en/perspectives/equityperspectives/finding-growth-in-an-increasingly-digital-world.html

http://www.zdnet.com/internet-of-things-8-9-trillion-market-in-2020-212-billion-connected-things-7000021516/

Dissecting an HTTP Request

Method

Path

Header

Body

Methods

GET: Requests a representation of the specified resource

POST: Requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI

PUT: Requests that the enclosed entity be stored under the supplied URI

PATCH: Apply partial modifications to a resource

DELETE: Deletes the specified resource

HEAD: Asks for the response identical to the one that would correspond to a GET request, but without the response body

OPTIONS: Returns the HTTP methods that the server supports for the specified URL

GET request

POST request

Dissecting an HTTP response

Status

Header

Body

HTTP response

http://www.slideshare.net/supercoco9/what-is-rest-why-is-it-part-of-the-rails-way-railsconf-2014-javier-ramirez

Defining an API

What to do...

...with what?

RPC

What to do?In the body

With what?In the body

POST /rpc HTTP/1.1Host: www.upcdatabase.comUser-Agent: XMLRPC::Client (Ruby 1.8.4)Content-Type: text/xml; charset=utf-8Content-Length: 158Connection: keep-alive

lookupUPC...

REST

What to do?In the HTTP method

With what?In the path

GET /hello.txt HTTP/1.1 Host: www.example.com

REST-RPC Hybrid

What to do?In the path

With what?In the path

GET services/rest?api_key=xxx&method=flickr.photos.search&tags=penguin HTTP/1.1Host: www.flickr.com

REST
(Representational State Transfer)

Roy Fielding (2000)Architecture for the web

Resources

resources

are not

models

Uniform and constrained interface

http://www.ibm.com/developerworks/websphere/techjournal/0903_peterson/0903_peterson.html

REST Principles (some)

Addressability

Addressability

/bands/iron_maiden/bands/the_beatles

/releases/20140529/releases/last

Representation oriented

Statelessness

HATEOAS (Hypermedia as the Engine of Application State)

Use methods and
response statuses well

Make your data format consistent

Versioning

https://invoicefu.com/es/developers/api_docs

https://developers.teowaki.com/api-overview

Questions?

Thanks

aspgems.com

fin