View
331
Download
0
Category
Tags:
Preview:
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.
Citation preview
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
Recommended