RESTful APIs: Promises & lies

RESTful APIs Promises & Lies!

Tareque (täreɪk)

what do all these companies have in common?

they thrive in their business using APIs

in fact, all of them provide RESTful APIs

all of them secure their APIs using Oauth

these facts are not coincidental

these companies made a choice

they chose to do their APIs right

so what is this talk about?

it’s about Web APIs

it’s about how we build APIs nowadays

nice & solid

we all have been building APIs for some time now

till this date, there are hardly any resource available

that tell you how to build APIs right

standards

best practices

we all learn them hard way

= magical API

Not really..

but you can make APIs magical

ask questions

is your API RESTful?

. stateless . cacheable . HTTP methods

take action depending on the type of HTTP request

GET -‐ retrieve POST -‐ create PUT -‐ update DELETE -‐ destroy

using these verbs API clients act on resources

your API is only as good as the resources it delivers

are your resources well deﬁned?

say you have a django project

it has a lot of models

attractive models

resource != model

resource = unit of information

that you own and everyone else wants a piece

deﬁne them with care

class Book (Model): title = Charfield(...) summary = Charfield(...) isbn10 = Charfield(...) isbn13 = Charfield(...) authors = ManyToManyField(...) created = DateTimeField(...)

{ ‘title’ : ‘...’, ‘summary’ : ‘...’, ‘authors’ : [‘...’, ‘...’], ‘editions’ : [{ ‘number’ : ‘...’, ‘publisher’ : ‘...’, ‘date_published’: ‘...’, }], ‘is_favorite’ : true, }

class Book (Model): title = Charfield(...) summary = Charfield(...) isbn10 = Charfield(...) isbn13 = Charfield(...) authors = ManyToManyField(...) created = DateTimeField(...) { ‘title’ : ‘...’, ‘summary’ : ‘...’, ‘authors’ : [‘...’, ‘...’], ‘editions’ : [{ ‘number’ : ‘...’, ‘publisher’ : ‘...’, ‘date_published’: ‘...’, }], ‘is_favorite’ : true, }

resource != model

concise & complete

but are resources the only thing you send in API responses?

resource structures vary wildly

API responses should be predictable

API responses should be parsable

API responses should be uniform

API RESPONSEwrap them in envelopes

add metadata about response

. HTTP status code . error code & message . pagination data

{ ‘status’ : 200, ‘errors’ : [], ‘data’ : { ‘title’ : ‘...’, ‘isbn10’ : ‘...’, ‘summary’ : ‘...’, ‘authors’ : [‘...’, ‘...’], } }

{ ‘status’ : 400, ‘errors’ : [{ ‘code’ : 5, ‘message’ : ‘OMG form errors!’, ‘data’ : { ‘title’: [‘Field required’], } }], ‘data’: {}, }

{ ‘status’ : 200, ‘errors’ : [], ‘data’ : { ‘pagination’: { ‘count’ : 134, ‘pages’ : 7, } ‘results’: [...], } }

now that you have uniform responses

ask yourself

would you support diﬀerent serialization formats?

the world is moving towards json

it’s a greener alternative to XML

but you might want to support jsonp

or XML

more formats = more testing

more formats = more support requests

it’s cool if you can accommodate

serialization parameters != cool format=xml

client can add .json or .xml at end of URL

Now you see it.. http://api.domain.com/v1.0/books/game-‐of-‐thrones.xml

Now you don’t.. http://api.domain.com/v1.0/books/game-‐of-‐thrones

in absence of speciﬁed format return default

then it’s all good

Did you notice that? http://api.domain.com/v1.0/books/game-‐of-‐thrones

versioning your API is cool

6 days of beer in Portland

your pants might not ﬁt

6 months of deployment in production

your APIs might not ﬁt

version your API

Why hello there! http://api.domain.com/v1.0/books/game-‐of-‐thrones

save URL namespace

now to one of the most important questions..

Is the anomaly systemic, creating ﬂuctuations in even the most simplistic equations?

always hated that guy

the question we are looking for is..

Is your API secure?

some endpoints need to be secure

private user data

resources that bring revenue

to protect resources, use an authentication scheme

use Oauth

use Oauth 1.0

use Oauth 2.0

use 2-‐legged Oauth for applications directly accessing resources

use 3-‐legged Oauth for applications accessing resources on behalf of users

use HTTPS for calls to protected resources

using Oauth might get a little complex

how to minimize that complexity?

what’s the easiest route to securing your API?

and making your API comply with the concepts we discussed?

bring us to the next question..

do you use any API frameworks?

django-‐piston

tastypie

django-‐rest-‐framework

dj-‐webmachine

take your pick

none of these frameworks will do everything for you

make them work for you

to build

we used django-‐piston

piston has built in Oauth support

and a ﬂexible architecture using pluggable components

pluggable resource handlers

pluggable emitters (serializers)

pluggable authentication

we enhanced django-‐piston

. pluggable envelopes . form error feedbacks . anonymous tokens

added resource deﬁnition subsystem

class BookDetailedView (PistonView): fields = [ ‘title’, ‘isbn10’, ‘pages’, Field( ‘’, lambda x: [y.name for y in x.authors.all()], destination=‘authors’, ), ]

return BookDetailedView(book)

{ ‘title’ : ‘...’, ‘isbn10’ : ‘...’, ‘pages’ : 357, ‘authors’ : [‘...’, ‘...’], }

http://github.com/pbs-‐education/django-‐piston

again, you have quite a few choices

. django-‐piston . tastypie . django-‐rest-‐framework . dj-‐webmachine

take your pick

make them work for you

build your API right

join the party

thank you

tarequeh -‐ slideshare.net -‐ twitter -‐ .com

http://lanyrd.com	341
http://siliconangle.com	43
https://twitter.com	2
http://twitter.com	1
http://leapf.org	1
http://translate.googleusercontent.com	1
http://paper.li	1
http://web1.conversationminer.com	1

RESTful APIs: Promises & lies

by Tareque Hossain

Accessibility

Categories

Upload Details

Usage Rights

8 Embeds 391

Statistics

RESTful APIs: Promises & lies Presentation Transcript