Embed Size (px)
DESCRIPTION
Fundamentals of building a Restful API with Django and django-rest-framework. Intended for new developers interested in developing a REST API for their applications. Basic knowledge of Python is nice to have, but the concepts are transferable. Presented at Vancouver Python Day 2013.
Citation preview
Building RESTful APIsVancouver Python Day
November 16, 2013
Ganesh Swamiwww.silota.com
Hi
• Programming professionally for 10+ years
• x86 assembly, STL, boost, python-boost, python
!
• Built emacs-‐wiki-‐blog: first blogging engine for Emacs!
SILOTA• Search As A Service
• full stack: crawling, indexing, retrieving, tag deployment
• Python shop:
• pelican
• ansible
• sentry
• django
• django-‐rest-‐framework
• In beta testing: love more feedback!
APIs: What & Why
What is an API?Application Programming Interface
!An API is the interface implemented by an
application which allows other applications to communicate with it.
What is an API?
communicate
What is REST?• REpresentational State Transfer
• logical resources manipulated with HTTP verbs
• modern best practice
• wide adoption
• contrast with SOAP
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
Sample APIs• aws
• dropbox
• github
• stripe
• salesforce
• parse
• …
Source: Mary Meeker’s Internet Trends 2013
APIs: How
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.
Resources, Status Codes &
Errors
Resources
• Nouns, not verbs
• Coarse grained, not fine grained
• example: let’s build a document datastore!
Smells like RPC• /getDocument
• /getAllDocuments
• /createDocument
• /updateDocument
• /deleteDocument
Smells like RPC• /getDocument
• /getAllDocuments
• /createDocument
• /updateDocument
• /deleteDocument
This is a bad example. !Don’t do this!
Embrace HTTP
• GET, POST, PUT, PATCH, DELETE
!
• Explorable with simple tools
Embrace HTTPGET /document Retrieve all documents
GET /document/19 Retrieve a specific document #19
POST /document Create a new document
PUT /document/19 Update an existing document #19
DELETE /document/19 Delete an existing document #19
Bipartite graph/documents /documents/:id …
GET
POST error
PUT error
PATCH error
DELETE
Status Codes
2xx OK, created, all good, carry on
4xx User error: bad API key, malformed data, item not found, etc.
5xx Server error
Errors
• Errors
• as descriptive as possible
• developers are your customers
• never naked 4xx/5xx HTTP errors
Errors
<xml version="1.0"?> <Error> <Message>A server error has occurred</Message> <Description>Unknown Error</Description> <Id>1234</Id> </Error>
Just no.
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’" }
pip-install httpie
Best practicessecurity
base URLs
serialization
timestamps
versioning
caching
gzip
logging
Best practicessecurity 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
Recap
• https + gzip + json
• draw bipartite graph of nouns and verbs
• great documentation
• no surprises
django-‐rest-‐framework
Why use a framework?
Myths
• roll your own
• use a ‘lightweight’ framework
• too tied to django
• too slow
Features• pagination
• permission
• authentication
• serialization
• throttling
• data validation
• proper HTTP response handling
Magic formula: MixinsViews Authentication Permissions Throttling
CreateAPIView Token Any SimpleRate
ListAPIView Session Token AnonRate
RetrieveAPIView OAuth Authentication
DeleteAPIView
Four step formula
1. create the model
2. write the serializer
3. write the view
4. configure the urls
References• How to Design a Good API and Why it Matters:
• http://lcsd05.cs.tamu.edu/slides/keynote.pdf
• Best Practices for Designing a Pragmatic RESTful API
• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• REST worst practices:
• http://jacobian.org/writing/rest-worst-practices/
• http://django-rest-framework.org/
