This document summarizes best practices for designing a REST API, provides examples of real-world REST APIs, and discusses tools for implementing REST APIs in Python. It recommends designing APIs with resources represented by nouns, using HTTP verbs to manipulate resources, and including documentation. Examples of Twitter, Twilio, and Amazon S3 APIs are given. Flask, Django, and TastyPie are presented as options for building REST APIs in Python.

1. KISS REST API
@yurevich, oDesk corp.
ekb.py 2012
1

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

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

4. REST
• stateless (no cookies & sessions)
• resources identification (URLs)
• representation (JSON, XML,YaML)
• manipulation of resources through
representation
• self-descriptive messages
• hypermedia (Links)
4

5. Good samples
• Twitter API
• Twilio API
• Amazon S3 API
5

6. Good practices
• Though not so universal
• http://blog.feedly.com/2009/05/06/best-
practices-for-building-json-rest-web-
services/
• http://jacobian.org/writing/rest-worst-
practices/
6

7. Writing spec
Document it first
• Real use-cases
• Complete and closed set
• Future kills now
• Explicit versioning
7

8. 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

9. 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
9

10. Namespaces
• https://smsgate/v2/messages
(or https://smsgate/20120210/messages) VS
https://smsgate/messages
10

11. Resources
• Resources are NOUNs
• https://smsgate/v2/messages VS
https://smsgate/v2/send-message
11

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

13. Auth! SSL!
• https://smsgate/v2/messages VS
http://smsgate/v2/messages
• Poor man auth: token-based
• Production ready: oAuth2
13

14. Real world sample 0
• SMS Gate
• GET http://smsgate/sendMessage?
number=780020000000&text=Send+it
+please
14

15. 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

16. 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/message’, ‘status’: ‘queued’}
16

17. Toolset
• Documentation
• Backend
• Validation
• JSON generation
• What’s next?
17

18. Toolset: documentation
• Sphinx (ReST)
• HTTP Domain — https://github.com/
deceze/Sphinx-HTTP-domain
• httpdomain — https://bitbucket.org/
birkenfeld/sphinx-contrib
• Markdown
• https://github.com/coopernurse/doctorj
18

19. Toolset: prototyping
• Red barrel
• External DSL (hello, PHP&Ruby)
• Self-documented
• Easy to distribute
• Only for prototyping
19

20. 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

21. 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
• It’s obsolete
21

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

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

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

25. Toolset:Validation
• https://github.com/Deepwalker/trafaret
• Very nice syntax
• Easy but supports complex nested
structures
• Lack of documentation
• No forms validation
25

26. Toolset: JSON writer
• /dev/hands
• Ruby:
• https://github.com/inem/tequila
• https://github.com/nesquena/rabl
26

27. What’s next?
• JSON Schema
• Validation
• Discovery
• http://json-schema.org/
• http://nico.vahlas.eu/2010/04/23/json-
schema-specifying-and-validating-json-data-
structures/
• http://shane.caraveo.com/2011/06/30/using-
json-schema-for-exploring-api-servers/
27

28. Surprise
• Dzen Python works for REST APIs
•curl http://pure-
dawn-9186.herokuapp.com/
import-this
28

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