KISS REST API

@yurevich, oDesk corp. ekb.py 2012

Plan
K.O. Good practices Real world sample Toolset
2

Good API
Easy to use to read to extend Complete Consistent
3

REST
stateless (no cookies & sessions) resources identication (URLs) representation (JSON, XML,YaML) manipulation of resources through
representation

self-descriptive messages hypermedia (Links)

4

Good samples
Twitter API Twilio API Amazon S3 API

Good practices
Though not so universal http://blog.feedly.com/2009/05/06/bestpractices-for-building-json-rest-webservices/ practices/

http://jacobian.org/writing/rest-worst6

Writing spec Document it rst

Real use-cases Complete and closed set Future kills now Explicit versioning
7

Beginners mistakes
Resource = model Think about married couple All methods should be implemented for
every resource

Update user account activation? Delete

sent SMS message?

Custom methods
8

Use nouns (learn passive voice)

User sends SMS message =>
A SMS message is created

Article is reviewed by editor =>

Review of article is created

The user deactivates account =>

User account activation is deleted

Namespaces
https://smsgate/v2/messages

(or https://smsgate/20120210/messages) VS https://smsgate/messages

10

Resources
Resources are NOUNs https://smsgate/v2/messages VS

https://smsgate/v2/send-message

11

URLs
Required GET params must be part of URL http://smsgate/v2/messages/{id} instead of
http://smsgate/v2/message?id={id}

12

Auth! SSL!
https://smsgate/v2/messages VS
http://smsgate/v2/messages

Poor man auth: token-based Production ready: oAuth2

13

Real world sample 0

SMS Gate GET http://smsgate/sendMessage?

number=780020000000&text=Send+it +please

14

Real world sample

SMS Gate Resource: Text Message /message: Create new one (send)
POST /messages

Get information about status

GET /messages/{id}

version: 2
15

Real world sample 2

POST https://smsgate2/v2/messages
> message=Send%20it %20please&target=780020000000

201 Created

Location: https://smsgate2/v2/messages/242 {target: 78002000000, url: https:// smsgate2/v2/messages/242, status: queued}

16

Toolset
Documentation Backend Validation JSON generation Whats next?
17

Toolset: documentation
Sphinx (ReST) HTTP Domain https://github.com/
deceze/Sphinx-HTTP-domain birkenfeld/sphinx-contrib

httpdomain https://bitbucket.org/ Markdown https://github.com/coopernurse/doctorj

18

Toolset: prototyping
https://github.com/mozilla-services/
redbarrel

External DSL (hello, PHP&Ruby) Self-documented Easy to distribute Only for prototyping
19

Flask
Simple You get what you need A lot of bootstrapping code Attention to details Chance to get hardcoded result In our projects most load-intensive APIs are
implemented using Flask
20

Django+Piston
Good set of features (for that time) Built-in formatters works well, on Accept header Methods are strictly mapped to actions Hard to reuse different forms in single
handler

Its obsolete
21

Django+TastyPie
A lot of features Pure Resource, ModelResource Pagination In our team richest APIs are implemented
in TastyPie

22

Toolset:Validation
http://bitbucket.org/jek/atland/ Looks cool Not so obvious for nested structures Internals OMG
23

Toolset:Validation
https://github.com/Deepwalker/procrustes Data and forms validation Simple Good as prototype, not so good for
production

lack of documentation
24

Toolset:Validation
https://github.com/Deepwalker/trafaret Very nice syntax Easy but supports complex nested
structures

Lack of documentation No forms validation

25

Toolset: JSON writer

/dev/hands Ruby: https://github.com/inem/tequila https://github.com/nesquena/rabl
26

Whats next?
JSON Schema Validation Discovery http://json-schema.org/ http://nico.vahlas.eu/2010/04/23/json-

schema-specifying-and-validating-json-datastructures/ json-schema-for-exploring-api-servers/

http://shane.caraveo.com/2011/06/30/using27

Surprise
Dzen Python works for REST APIs curl http://pure-

dawn-9186.herokuapp.com/ import-this

28

Thanks
Questions? yyurevich@jellycrystal.com follow me on twitter @yurevich

29