The document discusses building valuable RESTful APIs. It covers defining value through business models like freemium and advertising. Best practices for API design include using HTTP verbs, response codes, and hypermedia controls. Resources should be grouped and versioning is important. Authentication, pagination, and documentation are also discussed. The goal is to build APIs that are easy to use and provide value to both businesses and developers.

1. BuildingValuable
RESTfulAPIs
Guillermo A. Fisher Hampton Roads PHP

2. Me
Guillermo A. Fisher
http(s)://<everywhere>/guillermoandrae

3. Agenda
The Web API Economy
Defining Value
Business Models
Design Best Practices
Resources

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

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

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

7. A crowdedmarket
API-first development is popular
Quality is an issue
Difficult for APIs to stand out
Not just a marketing problem

8. MostpopularWebAPIs
Facebook, Google Maps, Twitter, YouTube,
AccuWeather, LinkedIn, Amazon Product
Advertising, Pinterest, Flickr, Google Talk

9. VALUE

10. Whatdobusinessesvalue?
$$$

11. Monetization
Direct
Indirect

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

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

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

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

16. Unrealizedpotential
“...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 2014
http://www.programmableweb.com/news/real-world-api-business-models-worked/analysis/2014/11/03

17. Whatdodevelopersvalue?
Reach/Audience
Ease of use
Access to valuable data
Access to markets

18. “Webuilta
RESTful
API…”

19. “Webuilta
RESTful-ish
API…”

20. APIdesign is
interfacedesign

21. “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 2013
http://searchsoa.techtarget.com/feature/Digging-into-quality-API-best-practices-problems-and-advice

22. Richardson
MaturityModel
(RMM)

23. TheGloryofREST
Level 3: Hypermedia Controls
Level 2: HTTP Verbs & Response Codes
Level 1: Resources
Level 0: The Swamp of POX

24. Listing Trader
Media Solutions
Online
http://api.listingtradermediasolutionsonline.com/rest
http://api.ltmso.io/rest

25. GET /search?color=dodger+blue
GET /getListing?id=42
GET /addListing?name=...
GET /deleteListing?id=42
GET /findProvider?id=718

26. GET /getListing?id=42 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
id: 42,
name: “Brooklyn’s Finest”,
color: “dodger blue”,
zip: 11234
}

27. GET /addListing?
name=Steel+City&color=black+and+gold&zip=15212
HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
id: 43,
name: “Steel City”,
color: “black and gold”,
zip: 15212
}

28. GET /getListing?id=summer HTTP/1.1
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=UTF-8
{
error: {
error: true,
message: “An error occurred”,
code: 347
}
}

29. Level0:TheSwamp of
POX
Use a protocol (HTTP) as a transport system
without indicating application state

30. Level1: 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 2012
https://restful-api-design.readthedocs.org/en/latest/resources.html

31. GET /search?color=dodger+blue
GET /getListing?id=42
GET /addListing?name=...
GET /deleteListing?id=42
GET /findProvider?id=718

32. Level1: Resources
Grouped into collections.
Represented as pluralized nouns.

33. Level1: Resources
/:collection
/:collection/:id
/:collection/:id/:sub-collection

34. GET /listings/search?color=dodger+blue
GET /listings/42
GET /listings
GET /providers/718

35. Level 2:HTTPVerbs
GET, HEAD
POST, PUT, PATCH, DELETE
OPTIONS

36. Level 2:HTTPVerbs
Accept a special header for clients that only
support GET and POST:
X-HTTP-Method-Override

37. GET /listings/search?color=dodger+blue
GET /listings/42
POST /listings
DELETE /listings/42
GET /providers/718

38. GET /listings/42/providers
POST /listings/42/providers
DELETE /listings/42/providers/718

39. Level2:HTTPResponse
Codes
2xx,4xx,5xx

40. 2xx = Stuff works
4xx = Client messed up
5xx = Server messed up

41. GET /listings/42 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
id: 42,
name: “Brooklyn’s Finest”,
color: “dodger blue”,
zip: 11234
}

42. POST /listings HTTP/1.1
{
name: “Steel City”,
zip: 15212
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
{
id: 43,
name: “Steel City”, …

43. GET /listings/summer HTTP/1.1
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
error: {
error: true,
message: “An error occurred”,
code: 347
}
}

44. Level 3: Hypermedia
Controls
HATEOAS (Pronounced “Hay-dee-us”)
Hypertext As The Engine Of Application State

45. WhatisHypertext?
“...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 2008
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

46. GET /listings/43 HTTP/1.1
HTTP/1.1 200 OK
Content-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”
}
}

47. ACHIEVEMENT UNLOCKED
Built a glorious RESTful API

48. Use SSL
https://api.ltmso.io/rest

49. Authentication
OAuth 2.0
Tokens in the Authorization header

50. GET /listings?offset=10&limit=10
GET /listings?page=2&per_page=10
Pagination

51. Link Header introduced by RFC5988
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Link: <https://api.ltmso.io/listings?offset=10>; rel="next",
<https://api.ltmso.io/listings?offset=60>; rel="last"
{
id: 1,
name: “Lonely Listing”, …
Pagination

52. Versioning
Don’t break client apps
Be consistent

53. HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
{
code: 347,
message: “Your request is malformed.”,
description: “Your request must include a valid listing
ID.”
}
InformativeErrors

55. Documentation
Specifications
API Blueprint
Swagger
RAML (RESTful API Modeling
Language)

56. APIExplorers

58. ResourcesThe Maturity Heuristic
http://www.crummy.com/writing/speaking/2008-QCon/act3.html
REST APIs must be hypertext-driven
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Richardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html
Thoughts on RESTful API Design
https://restful-api-design.readthedocs.org/en/latest/
API Best Practices Blog
https://blog.apigee.com/taglist/restful
ProgrammableWeb
http://www.programmableweb.com/