apis - the good, the bad & the ugly
DESCRIPTION
This describes what are the best practices of writing RESTful APIs. What are the different tools to create and test these APIs? What are the common pitfalls and how to avoid them? What are some of the industries best public APIs, etc. This also includes a quick and easy hands-on session to fire and launch some APIs in the cloud using Play! Framework.TRANSCRIPT
![Page 1: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/1.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT ! { !
} !
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 2: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/2.jpg)
API
![Page 3: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/3.jpg)
REST as a Guide
![Page 4: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/4.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/8913
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 5: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/5.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/1234
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 6: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/6.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/1234
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 7: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/7.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/1234
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 8: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/8.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/1234
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 9: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/9.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !
GET https://api.example.com/user/1234
"talk": apis – the good, the bad & the ugly, !"name” : nikhil bendre, !"twitter” : @npbendre, !“site”: npbendre.com!
![Page 10: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/10.jpg)
api.example.com/me
![Page 11: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/11.jpg)
http://maps.company.com/maps/api/ staticmap?center=Brooklyn+Bridge,New!+York,NY&zoom=13&size=600x300&maptype=road map&markers=color:blue%7Clabel:S!%7C40.702147,-74.015794&markers=color:gree n%7Clabel:G%7C40.711614,-74.012318!&markers=color:red%7Ccolor:red%7Clabel:C!%7C40.718217,-73.998284&sensor=false!
![Page 12: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/12.jpg)
FIRST: DEFINE RESOURCES A Good Approach: Structure Your URLs
![Page 13: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/13.jpg)
what if /createUser
/getDirectory
/verifyUser
/updateUser
/createEvent
![Page 14: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/14.jpg)
what if /createUser
/getDirectory
/verifyUser
/updateUser
/createEvent
/verifyEvent
/deleteUser
/updateUser
/updateUserName
…………………….
![Page 15: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/15.jpg)
collection &
instance
/files /files/982
![Page 16: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/16.jpg)
SECOND: USE RESOURCES CRUD, but not really
![Page 17: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/17.jpg)
Partially update a resource
GET
POST
PUT
DELETE
PATCH
Retrieve resource
Create resource
Update a resource
Delete a resource
HEAD Get only the headers
![Page 18: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/18.jpg)
Media Type
Request: Accept header
Response: Content-Type header
![Page 19: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/19.jpg)
Meaningful Response Code
![Page 20: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/20.jpg)
![Page 21: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/21.jpg)
2xx: Success
3xx: Redirection
4xx: Client Error
5xx: Server Error
![Page 22: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/22.jpg)
Bad {“error”: “code 782” }
Good HTTP 1.1 400 {
“error” : “field was missing”, “link” : “apidocs.com/400”,
}
error response
![Page 23: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/23.jpg)
Versioning
![Page 24: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/24.jpg)
Accept
Content-Type
application/json+foo;application&v1
https://api.example.com/v1
vs
![Page 25: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/25.jpg)
ETAGS ARE COOL. NOBODY USES’EM
![Page 26: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/26.jpg)
HTTP/1.1 !Server: !
200 OK !nginx !
Date:"Wed, 14 Content-Type: !
Sep 2014 14:03:33 !application/json; !
GMT !charset=utf-8 !
Connection: Status: 200 !
keep-alive OK !
ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT ! { !
} !“data”: …!
Server Response
![Page 27: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/27.jpg)
HTTP/1.1 ! 304 Not Modified!Date:"Wed, 14 ! Sep 2014 14:03:33 ! GMT !Last-Modified: Sat, 13 Sep 2014 10:53:21 GMT !
Client Request
curl -i -H "If-None-Match: \"ef742caec0c19e2169ffb05e7d200d17\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"!
![Page 28: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/28.jpg)
HYPERMEDIA
![Page 29: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/29.jpg)
SUN CLOUD API
GET /machines/1/ Host: example.com Accept: application/xml
Sample Request
![Page 30: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/30.jpg)
HTTP/1.1 200 OK Content-Type: application/xml <status>stopped</status> <link rel="start" method="post" href="machines/2?op=start" />
Sample Response
![Page 31: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/31.jpg)
Security
![Page 32: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/32.jpg)
Photo by Tojosan - Creative Commons Attribution-NonCommercial-ShareAlike License https://www.flickr.com/photos/28069288@N00 Created with Haiku Deck
![Page 33: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/33.jpg)
![Page 34: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/34.jpg)
![Page 35: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/35.jpg)
![Page 36: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/36.jpg)
Models
Proprietary Solution Basic Authentication
OAuth 1.0 OAuth 2.0
![Page 37: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/37.jpg)
Make Docs Obvious
![Page 38: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/38.jpg)
![Page 39: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/39.jpg)
Supported Options
Examples
Required & Optional Attributes
Default Values
Error Codes
![Page 40: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/40.jpg)
Automate
![Page 41: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/41.jpg)
![Page 42: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/42.jpg)
![Page 43: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/43.jpg)
![Page 44: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/44.jpg)
Build something
meaningful
with your
APIs
![Page 45: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/45.jpg)
![Page 46: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/46.jpg)
![Page 47: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/47.jpg)
RATE LIMIT
![Page 48: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/48.jpg)
Photo by GirlieMac - Creative Commons Attribution License https://www.flickr.com/photos/70561195@N00 Created with Haiku Deck
![Page 49: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/49.jpg)
CHATTY API
![Page 50: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/50.jpg)
Let’s
Play!
![Page 51: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/51.jpg)
Download Play 2.3.4
![Page 52: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/52.jpg)
Compile, Run & Test
activator new
select template & name
activator run
![Page 53: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/53.jpg)
![Page 54: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/54.jpg)
Controllers GET / controllers.Application.index() GET /users ...getUsers() GET /users/:id ...getUserById(id: String) …
![Page 55: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/55.jpg)
Models
Ebeans for Java
JPA Annotations
Versioned Evolution Scripts
![Page 56: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/56.jpg)
Test
Based on JUnit
Mockito
Integration & UI Test
![Page 57: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/57.jpg)
Pros
Easy Url routing
Class Reloading
Java&Scala support
Java/Ebean support
NIO Server
![Page 58: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/58.jpg)
TEST & PERFORMANCE
![Page 59: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/59.jpg)
RUNSCOPE
![Page 60: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/60.jpg)
Thanks
![Page 61: APIs - the good, the bad & the ugly](https://reader033.vdocuments.site/reader033/viewer/2022042816/5590a1891a28abfe788b45eb/html5/thumbnails/61.jpg)
Attributions • Cat by Marco Petrucci from The Noun Project • Chat by Alberto Guerra Quintanilla from The Noun Project • Coffee by Monika Ciapala from The Noun Project • Key by Simple Icons from The Noun Project • Lock by Jardson A. from The Noun Project • Magnifying Glass by Naomi Atkinson from The Noun Project • Gauge by Olivier Guin from The Noun Project • Lock by Andrew Forrester from The Noun Project • Fork by Dmitry Baranovskiy from The Noun Project • Click icon is open source • Document icon by Joe Richardson from The Noun Project • Robot icon by Jon Trillana • Tasks list by Arthur Shlain from The Noun Project • Graph by David Waschbüsch from The Noun Project • HTTP cats photo from girliemac • Photo by Tojosan