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/messages/242’, ‘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
• https://github.com/mozilla-services/
redbarrel
• 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