RESTful APIs: Promises & lies

RESTful APIs

Promises & Lies

Tareque (täreɪk)

what do all these companies have in

common?

they thrive in their businessusing 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 - retrievePOST - createPUT - updateDELETE - destroy

using these verbs API clients act on resources

your API is only as good as the resources it delivers

are your resources well defined?

say you have a django project

it has a lot of models

attractive models

resource != model

resource = unit of information

that you ownand everyone else wants a piece

define 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

wrap them in envelopes

APIRESPONSE

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 different 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 != coolformat=xml

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

http://api.domain.com/v1.0/books/game-of-

thrones.xml

Now you see it..

http://api.domain.com/v1.0/books/game-

of-thrones

Now you don’t..

in absence of specified format return default

then it’s all good

http://api.domain.com/v1.0/books/game-

of-thrones

Did you notice that?

versioning your API is cool

6 days of beer in Portland

your pants might not fit

6 months of deployment in production

your APIs might not fit

version your API

http://api.domain.com/v1.0/books/game-

of-thrones

Why hello there!

save URL namespace

now to one of the most important questions..

Is the anomaly systemic, creating

fluctuations 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 anauthentication 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 flexible 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 definitionsubsystem

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