Professional Documents
Culture Documents
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
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
Beginners mistakes
Resource = model Think about married couple All methods should be implemented for
every resource
Custom methods
8
Namespaces
https://smsgate/v2/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
13
number=780020000000&text=Send+it +please
14
version: 2
15
201 Created
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
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
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