Building RESTful APIs
13 likes4,672 views
The document discusses the essentials of building RESTful APIs using Python, highlighting key concepts such as the definition of APIs, the principles of REST, and best practices for API design. It emphasizes the importance of intuitive documentation, error handling, and security measures while also advocating the use of Django REST Framework for effective API development. The presentation includes examples and resources to aid in understanding API functionality and implementation.
Building RESTful APIs
- 1. Building RESTful APIs Vancouver Python Day November 16, 2013 Ganesh Swami www.silota.com
- 2. Hi • Programming professionally for 10+ years • x86 assembly, STL, boost, python-boost, python ! • Built emacs-‐wiki-‐blog: first blogging engine for Emacs!
- 3. SILOTA • Search As A Service • • full stack: crawling, indexing, retrieving, tag deployment Python shop: • • ansible • sentry • django • • pelican django-‐rest-‐framework In beta testing: love more feedback!
- 4. APIs: What & Why
- 5. What is an API? Application Programming Interface ! An API is the interface implemented by an application which allows other applications to communicate with it.
- 6. What is an API? communicate
- 7. What is REST? • REpresentational State Transfer • logical resources manipulated with HTTP verbs • modern best practice • wide adoption • contrast with SOAP
- 8. Why build an API? • explosion of devices connected to the internet • can be a company’s greatest asset • bizdev 2.0: internal developers, consultants, partners, customers
- 10. Source: Mary Meeker’s Internet Trends 2013
- 11. APIs: How
- 12. Top 3 qualities • Intuitive • • no surprises, easy to learn Documented • • • simple answers to simple questions references, tutorials & quick starts Opinionated • camelCase, ids, responses, pagination, etc.
- 15. Resources • Nouns, not verbs • Coarse grained, not fine grained • example: let’s build a document datastore!
- 16. Smells like RPC • /getDocument • /getAllDocuments • /createDocument • /updateDocument • /deleteDocument
- 17. Smells like RPC • /getDocument • /getAllDocuments • /createDocument • /updateDocument • /deleteDocument This is a bad example. ! Don’t do this!
- 18. Embrace HTTP • GET, POST, PUT, PATCH, DELETE ! • Explorable with simple tools
- 19. Embrace HTTP GET /document GET /document/19 POST /document Retrieve all documents Retrieve a specific document #19 Create a new document PUT /document/19 Update an existing document #19 DELETE /document/19 Delete an existing document #19
- 21. Status Codes 2xx OK, created, all good, carry on 4xx User error: bad API key, malformed data, item not found, etc. 5xx Server error
- 22. Errors • Errors • as descriptive as possible • developers are your customers • never naked 4xx/5xx HTTP errors
- 23. Errors <xml version="1.0"?> <Error> <Message>A server error has occurred</Message> <Description>Unknown Error</Description> <Id>1234</Id> </Error> Just no.
- 24. Errors { "code" : 1234, "message" : "Unsupported media type ‘text/html’ in request", "description" : "Requests need to have the Content-‐Type HTTP header set to ‘application/json’" }
- 27. Best practices security https all the way base URLs api.companyname.com serialization json timestamps ISO 8601 & UTC versioning /v1/ caching ETag & Last-Modified gzip always & pretty print responses logging if possible
- 28. Recap • https + gzip + json • draw bipartite graph of nouns and verbs • great documentation • no surprises
- 30. Why use a framework?
- 31. Myths • roll your own • use a ‘lightweight’ framework • too tied to django • too slow
- 32. Features • pagination • permission • authentication • serialization • throttling • data validation • proper HTTP response handling
- 34. Four step formula 1. create the model 2. write the serializer 3. write the view 4. configure the urls
- 35. References • How to Design a Good API and Why it Matters: • • Best Practices for Designing a Pragmatic RESTful API • • http://www.vinaysahni.com/best-practices-for-a-pragmaticrestful-api REST worst practices: • • http://lcsd05.cs.tamu.edu/slides/keynote.pdf http://jacobian.org/writing/rest-worst-practices/ http://django-rest-framework.org/
- 36. Keep in touch! Ganesh Swami! www.silota.com ganesh@silota.com @gane5h