ekb.py: KISS REST API
0 likes1,698 views
This document summarizes best practices for designing a REST API, including making the API easy to use, read, and extend. It provides real-world examples and discusses tools for documentation, validation, and JSON generation. Key recommendations include using nouns for resources, explicit versioning, token-based or OAuth authentication, and representing resources as complete URLs.
Ad
More Related Content
What's hot (16)
Viewers also liked (6)
Ad
Similar to ekb.py: KISS REST API (20)
Ad
More from Yury Yurevich (7)
Recently uploaded (20)
ekb.py: KISS REST API
- 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? • [email protected] • follow me on twitter @yurevich 29