Building Valuable RESTful APIs
-
Upload
hampton-roads-php-user-grop -
Category
Software
-
view
19 -
download
2
Transcript of Building Valuable RESTful APIs
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
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
“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
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 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 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”
}}
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
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
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/