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 !





keep-alive OK !

ETag: ! "ef742caec0c19e2169ffb05e7d200d17" !Last-Modified: Sat, 13 Sep 2014 10:52:21 GMT !!{ ! } !

GET https://api.example.com/user/8913


HTTP/1.1 !Server: !

200 OK !nginx !





keep-alive OK !




HTTP/1.1 !Server: !

200 OK !nginx !





keep-alive OK !




HTTP/1.1 !Server: !

200 OK !nginx !





keep-alive OK !




HTTP/1.1 !Server: !

200 OK !nginx !





keep-alive OK !




HTTP/1.1 !Server: !

200 OK !nginx !





keep-alive OK !




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 !





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

Software

APIs - the good, the bad & the ugly