APIs - the good, the bad & the ugly
-
Upload
nikhil-bendre -
Category
Software
-
view
331 -
download
0
description
Transcript of APIs - the good, the bad & the ugly
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!
API
REST as a Guide
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!
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!
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!
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!
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!
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!
api.example.com/me
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!
FIRST: DEFINE RESOURCES A Good Approach: Structure Your URLs
what if /createUser
/getDirectory
/verifyUser
/updateUser
/createEvent
what if /createUser
/getDirectory
/verifyUser
/updateUser
/createEvent
/verifyEvent
/deleteUser
/updateUser
/updateUserName
…………………….
collection &
instance
/files /files/982
SECOND: USE RESOURCES CRUD, but not really
Partially update a resource
GET
POST
PUT
DELETE
PATCH
Retrieve resource
Create resource
Update a resource
Delete a resource
HEAD Get only the headers
Media Type
Request: Accept header
Response: Content-Type header
Meaningful Response Code
2xx: Success
3xx: Redirection
4xx: Client Error
5xx: Server Error
Bad {“error”: “code 782” }
Good HTTP 1.1 400 {
“error” : “field was missing”, “link” : “apidocs.com/400”,
}
error response
Versioning
Accept
Content-Type
application/json+foo;application&v1
https://api.example.com/v1
vs
ETAGS ARE COOL. NOBODY USES’EM
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
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=___"!
HYPERMEDIA
SUN CLOUD API
GET /machines/1/ Host: example.com Accept: application/xml
Sample Request
HTTP/1.1 200 OK Content-Type: application/xml <status>stopped</status> <link rel="start" method="post" href="machines/2?op=start" />
Sample Response
Security
Photo by Tojosan - Creative Commons Attribution-NonCommercial-ShareAlike License https://www.flickr.com/photos/28069288@N00 Created with Haiku Deck
Models
Proprietary Solution Basic Authentication
OAuth 1.0 OAuth 2.0
Make Docs Obvious
Supported Options
Examples
Required & Optional Attributes
Default Values
Error Codes
Automate
Build something
meaningful
with your
APIs
RATE LIMIT
Photo by GirlieMac - Creative Commons Attribution License https://www.flickr.com/photos/70561195@N00 Created with Haiku Deck
CHATTY API
Let’s
Play!
Download Play 2.3.4
Compile, Run & Test
activator new
select template & name
activator run
Controllers GET / controllers.Application.index() GET /users ...getUsers() GET /users/:id ...getUserById(id: String) …
Models
Ebeans for Java
JPA Annotations
Versioned Evolution Scripts
Test
Based on JUnit
Mockito
Integration & UI Test
Pros
Easy Url routing
Class Reloading
Java&Scala support
Java/Ebean support
NIO Server
TEST & PERFORMANCE
RUNSCOPE
Thanks
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