KISS REST API @yurevich, oDesk corp.     ekb.py 2012                          1
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 identification (URLs)• representation (JSON, XML,YaML)• manipulation of ...
Good samples• Twitter API• Twilio API• Amazon S3 API                     5
Good practices• Though not so universal• http://blog.feedly.com/2009/05/06/best-  practices-for-building-json-rest-web-  s...
Writing spec    Document it first• Real use-cases• Complete and closed set• Future kills now• Explicit versioning          ...
Beginners mistakes• Resource = model • Think about married couple• All methods should be implemented for  every resource •...
Use nouns  (learn passive voice)• User sends SMS message =>  A SMS message is created• Article is reviewed by editor =>  R...
Namespaces• https://smsgate/v2/messages  (or https://smsgate/20120210/messages) VS  https://smsgate/messages              ...
Resources• Resources are NOUNs• https://smsgate/v2/messages VS  https://smsgate/v2/send-message                           ...
URLs• Required GET params must be part of URL • http://smsgate/v2/messages/{id} instead of    http://smsgate/v2/message?id...
Auth! SSL!• https://smsgate/v2/messages VS  http://smsgate/v2/messages• Poor man auth: token-based• Production ready: oAut...
Real world sample 0• SMS Gate • GET http://smsgate/sendMessage?    number=780020000000&text=Send+it    +please            ...
Real world sample• SMS Gate • Resource: Text Message /message:    • Create new one (send) —        POST /messages     • Ge...
Real world sample 2• POST https://smsgate2/v2/messages  > message=Send%20it  %20please&target=780020000000• 201 Created  L...
Toolset• Documentation• Backend• Validation• JSON generation• What’s next?                       17
Toolset: documentation• Sphinx (ReST) • HTTP Domain — https://github.com/    deceze/Sphinx-HTTP-domain • httpdomain — http...
Toolset: prototyping• Red barrel • External DSL (hello, PHP&Ruby) • Self-documented • Easy to distribute • Only for protot...
Flask• Simple• You get what you need• A lot of bootstrapping code • Attention to details • Chance to get hardcoded result•...
Django+Piston• Good set of features (for that time)• Built-in formatters • works well, on Accept header• Methods are stric...
Django+TastyPie• A lot of features• Pure Resource, ModelResource• Pagination• In our team richest APIs are implemented  in...
Toolset:Validation• http://bitbucket.org/jek/flatland/ • Looks cool • Not so obvious for nested structures • Internals — OM...
Toolset:Validation• https://github.com/Deepwalker/procrustes • Data and forms validation • Simple • Good as prototype, not...
Toolset:Validation• https://github.com/Deepwalker/trafaret • Very nice syntax • Easy but supports complex nested    struct...
Toolset: JSON writer• /dev/hands• Ruby: • https://github.com/inem/tequila • https://github.com/nesquena/rabl              ...
What’s next?• JSON Schema • Validation • Discovery• http://json-schema.org/• http://nico.vahlas.eu/2010/04/23/json-  schem...
Surprise• Dzen Python works for REST APIs•curl http://pure-  dawn-9186.herokuapp.com/  import-this                        ...
Thanks• Questions?• yyurevich@jellycrystal.com• follow me on twitter @yurevich                                   29
Upcoming SlideShare
Loading in...5
×

ekbpy'2012- Юрий Юревич - Как сделать REST API на Python

2,998

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,998
On Slideshare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
4
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Transcript of "ekbpy'2012- Юрий Юревич - Как сделать REST API на Python"

  1. 1. KISS REST API @yurevich, oDesk corp. ekb.py 2012 1
  2. 2. Plan• K.O.• Good practices• Real world sample• Toolset 2
  3. 3. Good API• Easy • to use • to read • to extend• Complete• Consistent 3
  4. 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. 5. Good samples• Twitter API• Twilio API• Amazon S3 API 5
  6. 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. 7. Writing spec Document it first• Real use-cases• Complete and closed set• Future kills now• Explicit versioning 7
  8. 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. 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. 10. Namespaces• https://smsgate/v2/messages (or https://smsgate/20120210/messages) VS https://smsgate/messages 10
  11. 11. Resources• Resources are NOUNs• https://smsgate/v2/messages VS https://smsgate/v2/send-message 11
  12. 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. 13. Auth! SSL!• https://smsgate/v2/messages VS http://smsgate/v2/messages• Poor man auth: token-based• Production ready: oAuth2 13
  14. 14. Real world sample 0• SMS Gate • GET http://smsgate/sendMessage? number=780020000000&text=Send+it +please 14
  15. 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. 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. 17. Toolset• Documentation• Backend• Validation• JSON generation• What’s next? 17
  18. 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. 19. Toolset: prototyping• Red barrel • External DSL (hello, PHP&Ruby) • Self-documented • Easy to distribute • Only for prototyping 19
  20. 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. 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. 22. Django+TastyPie• A lot of features• Pure Resource, ModelResource• Pagination• In our team richest APIs are implemented in TastyPie 22
  23. 23. Toolset:Validation• http://bitbucket.org/jek/flatland/ • Looks cool • Not so obvious for nested structures • Internals — OMG 23
  24. 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. 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. 26. Toolset: JSON writer• /dev/hands• Ruby: • https://github.com/inem/tequila • https://github.com/nesquena/rabl 26
  27. 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. 28. Surprise• Dzen Python works for REST APIs•curl http://pure- dawn-9186.herokuapp.com/ import-this 28
  29. 29. Thanks• Questions?• yyurevich@jellycrystal.com• follow me on twitter @yurevich 29
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×