ekbpy'2012- Юрий Юревич - Как сделать REST API на Python
0 likes•1,830 views
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.
ekbpy'2012- Юрий Юревич - Как сделать REST API на 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? • [email protected] • follow me on twitter @yurevich 29