Building Valuable RESTful APIs

Guillermo A. Fisher Hampton Roads PHP

MeGuillermo A. Fisher

http(s)://<everywhere>/guillermoandrae

AgendaThe Web API Economy

Defining ValueBusiness Models

Design Best PracticesResources

Growth in Web APIs since 2005

ProgrammableWeb, Based on APIs registered between 2005 & 2013http://www.programmableweb.com/api-research

Web API protocols & styles since 2005

ProgrammableWeb, Based on APIs registered between 2005 & 2011http://www.slideshare.net/jmusser/open-apis-state-of-the-market-2011

Web API searches since 2004

Google Trends, Based on Google searches between 2004 & 2014http://www.google.com/trends/explore#q=REST%20API%2C%20SOAP%20API%2C%20XML-RPC%20API&cmpt=q

A crowded market API-first development is popular

Quality is an issueDifficult for APIs to stand outNot just a marketing problem

Most popular Web APIsFacebook, Google Maps, Twitter, YouTube, AccuWeather, LinkedIn, Amazon Product Advertising, Pinterest, Flickr, Google Talk

VALUE

What do businesses value?

$$$

MonetizationDirect

Indirect

Popular API business models

John Musser, ProgrammableWeb.com, “Open APIs: What’s Hot, What’s Not?”, 2012http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012

Popular API business models

John Musser, ProgrammableWeb.com, “Open APIs: What’s Hot, What’s Not?”, 2012http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012

Popular API business models

John Musser, ProgrammableWeb.com, “Open APIs: What’s Hot, What’s Not?”, 2012http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012

Popular API business models

John Musser, ProgrammableWeb.com, “Open APIs: What’s Hot, What’s Not?”, 2012http://www.slideshare.net/jmusser/j-musser-apishotnotgluecon2012

Unrealized potential“...API businesses...are implementing only a few

strategies...this could indicate signs of money being left on the table as business’ [sic] are not taking full

advantage of the growth that comes from using all of the best practices in API design and delivery.”

Mark Boyd, “Real World API Business Models That Worked”, November 2014http://www.programmableweb.com/news/real-world-api-business-models-worked/analysis/2014/11/03

What do developers value?Reach/Audience

Ease of useAccess to valuable data

Access to markets

“We built a

RESTful API…”

“We built a

RESTful-ish API…”

API design is interface design

“For consumers, a bad API means a longer development cycle and a higher defect

rate; and in some cases, even a skills problem in the team -- a dependency on the

one person that mastered the black art of calling the API correctly.”

Peter Hendriks, Infosupport, September 2013http://searchsoa.techtarget.com/feature/Digging-into-quality-API-best-practices-problems-and-advice

Richardson Maturity Model

(RMM)

The Glory of RESTLevel 3: Hypermedia Controls

Level 2: HTTP Verbs & Response CodesLevel 1: Resources

Level 0: The Swamp of POX

Listing Trader Media Solutions

Onlinehttp://api.listingtradermediasolutionsonline.com/rest

http://api.ltmso.io/rest

GET /search?color=dodger+blue

GET /getListing?id=42

GET /addListing?name=...

GET /deleteListing?id=42

GET /findProvider?id=718

GET /getListing?id=42 HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{id: 42,name: “Brooklyn’s Finest”,color: “dodger blue”,zip: 11234

}

GET /addListing?name=Steel+City&color=black+and+gold&zip=15212 HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{id: 43,name: “Steel City”,color: “black and gold”,zip: 15212

}

GET /getListing?id=summer HTTP/1.1

HTTP/1.1 500 Internal Server ErrorContent-Type: application/json; charset=UTF-8

{error: {

error: true,message: “An error occurred”,code: 347

}}

Level 0: The Swamp of POX

Use a protocol (HTTP) as a transport system without indicating application state

Level 1: Resources“A resource is an object with a type,

associated data, relationships to other resources, and a set of methods that operate

on it.”

Geert Jansen, “Thoughts on RESTful API Design”, November 2012https://restful-api-design.readthedocs.org/en/latest/resources.html

GET /search?color=dodger+blue

GET /getListing?id=42

GET /addListing?name=...

GET /deleteListing?id=42

GET /findProvider?id=718

Level 1: ResourcesGrouped into collections.

Represented as pluralized nouns.

Level 1: Resources/:collection

/:collection/:id

/:collection/:id/:sub-collection

GET /listings/search?color=dodger+blue

GET /listings/42

GET /listings

GET /providers/718

Level 2: HTTP Verbs

GET, HEADPOST, PUT, PATCH, DELETE

OPTIONS

Level 2: HTTP VerbsAccept a special header for clients that only

support GET and POST:

X-HTTP-Method-Override

GET /listings/search?color=dodger+blue

GET /listings/42

POST /listings

DELETE /listings/42

GET /providers/718

GET /listings/42/providers

POST /listings/42/providers

DELETE /listings/42/providers/718

Level 2: HTTP Response Codes

2xx,4xx,5xx

2xx = Stuff works

4xx = Client messed up

5xx = Server messed up

GET /listings/42 HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{id: 42,name: “Brooklyn’s Finest”,color: “dodger blue”,zip: 11234

}

POST /listings HTTP/1.1{

name: “Steel City”,zip: 15212

}

HTTP/1.1 201 CreatedContent-Type: application/json; charset=UTF-8

{id: 43,name: “Steel City”, …

GET /listings/summer HTTP/1.1

HTTP/1.1 400 Bad RequestContent-Type: application/json; charset=UTF-8

{error: {

error: true,message: “An error occurred”,code: 347

}}

Level 3: Hypermedia Controls

HATEOAS (Pronounced “Hay-dee-us”)Hypertext As The Engine Of Application State

What is Hypertext?“...the simultaneous presentation of

information and controls such that the information becomes the affordance through

which the user (or automation) obtains choices and selects actions.”

Roy T. Fielding, “REST APIs must by hypertext-driven”, October 2008http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

GET /listings/43 HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8

{id: 43,name: “Steel City”,color: “black and gold”,zip: 15212,links: {

self: “/listings/43”,providers: “/listings/43/providers”,html: “http://ltmso.io/listing/Thing/43”,rss: “http://ltmso.io/feeds/listings/43.rss”

}}

ACHIEVEMENT UNLOCKEDBuilt a glorious RESTful API

Use SSLhttps://api.ltmso.io/rest

AuthenticationOAuth 2.0

Tokens in the Authorization header

GET /listings?offset=10&limit=10

GET /listings?page=2&per_page=10

Pagination

Link Header introduced by RFC5988

HTTP/1.1 200 OKContent-Type: application/json; charset=UTF-8Link: <https://api.ltmso.io/listings?offset=10>; rel="next",

<https://api.ltmso.io/listings?offset=60>; rel="last"

{id: 1,name: “Lonely Listing”, …

Pagination

VersioningDon’t break client apps

Be consistent

HTTP/1.1 400 Bad RequestContent-Type: application/json; charset=UTF-8

{code: 347,message: “Your request is malformed.”,description: “Your request must include a valid listing

ID.”}

Informative Errors

Documentation Specifications

API BlueprintSwagger

RAML (RESTful API Modeling Language)

API Explorers

ResourcesThe Maturity Heuristic

http://www.crummy.com/writing/speaking/2008-QCon/act3.html

REST APIs must be hypertext-drivenhttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Richardson Maturity Modelhttp://martinfowler.com/articles/richardsonMaturityModel.html

Thoughts on RESTful API Designhttps://restful-api-design.readthedocs.org/en/latest/

API Best Practices Bloghttps://blog.apigee.com/taglist/restful

ProgrammableWebhttp://www.programmableweb.com/