Prototyping APIs with Flask

PROTOTYPING
NEW APIS 
WITH FLASK
DAVID BAUMGOLD
@SINGINGWOLFBOY
TUESDAY MAY 31
PYCON 2016 IN PORTLAND
slides: bit.ly/flask-api-pycon-2016 
code: github.com/singingwolfboy/build-a-flask-api

View Slide

APIS CONNECT THE WORLD
So hot 
right now
bit.ly/flask-api-pycon-2016

View Slide

LET’S BUILD ONE!

View Slide

YOU’VE ONLY GOT ONE WEEK

View Slide

LET’S BUILD ONE!
FAST!

View Slide

WHAT DO WE WANT?
• JSON data format
• CRUD operations
• REST semantics
• Flexible code
(create, read, update, delete)
(it’s a prototype!)

View Slide

WHAT DO WE NOT CARE ABOUT?
• Stability & testing
• Long-term maintainability
• Edge cases
• Operations & deployment
IT’S ONLY A PROTOTYPE!

View Slide

DAY ONE

View Slide

HELLO WORLD
from flask import Flask
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello World!"
if __name__ == "__main__":
app.run()

View Slide

HELLO JSON
from flask import Flask, jsonify
@app.route("/")
def hello():
return jsonify({"message": "Hello, World!"})
if __name__ == "__main__":
app.run()

View Slide

View Slide

HELLO ROVER
@app.route("/")
def get_puppy():
puppy = {
"name": "Rover",
"image_url": "http://example.com/rover.jpg",
}
return jsonify(puppy)
if __name__ == "__main__":
app.run()

View Slide

from flask import Flask, jsonify, abort
PUPPIES = [
{
"name": "Rover",
},
{
"name": "Spot",
"image_url": "http://example.com/spot.jpg",
},
]
@app.route("/")
def get_puppy(index):
try:
puppy = PUPPIES[index]
except IndexError:
abort(404)
if __name__ == "__main__":
app.run()

View Slide

/0
/1
/2

View Slide

from flask import Flask, jsonify, abort
PUPPIES = {
"rover": {
"name": "Rover",
},
"spot": {
"name": "Spot",
},
}
@app.route("/")
def get_puppy(slug):
try:
puppy = PUPPIES[slug]
except KeyError:
abort(404)
if __name__ == "__main__":
app.run()

View Slide

/rover
/spot
/lassie

View Slide

IT WORKS!
Good news:
Bad news:
ONLY STATIC 
DATA

View Slide

DAY TWO

View Slide

SEPARATION OF CONCERNS
Database
contains data
View
transforms data
to JSON

View Slide

Object Relational Mapper (ORM)

View Slide

SQLALCHEMY MODEL
models.py
fast lookup by slug
required values
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()
class Puppy(db.Model):
id = db.Column(db.Integer, primary_key=True)
slug = db.Column(db.String(64), index=True)
name = db.Column(db.String(64), nullable=False)
image_url = db.Column(db.String(128), nullable=False)

View Slide

INSERT INTO DATABASE
# create a Puppy object, and add it to the session
p1 = Puppy(slug="rover", name="Rover",
image_url="http://example.com/rover.jpg")
db.session.add(p1)
# create and add a second Puppy
p2 = Puppy(slug="spot", name="Spot",
image_url="http://example.com/spot.jpg")
db.session.add(p2)
# changes won't be saved until committed!
db.session.commit()

View Slide

QUERY DATABASE
# .all() returns a list
all_puppies = Puppy.query.all()
len(all_puppies) == 2
# .first() returns the first item that matches
spot = Puppy.query.filter(Puppy.slug=="spot").first()
spot.name == "Spot"
spot.image_url == "http://example.com/spot.jpg"
# .filter_by() is a shortcut
rover = Puppy.query.filter_by(slug="rover").first()
rover.name == "Rover"
rover.image_url == "http://example.com/rover.jpg"
# if no matches, .first() returns None
lassie = Puppy.query.filter_by(slug="lassie").first()
lassie == None

View Slide

UPDATE DATABASE
# query to get a Puppy object
spot = Puppy.query.filter(Puppy.slug=="spot").first()
spot.image_url == "http://example.com/spot.jpg"
# update image_url
spot.image_url = "http://example.com/adorable.jpg"
# updates won't be saved until committed
db.session.add(spot)
db.session.commit()
# query again, and it's updated!
p2 = Puppy.query.filter(Puppy.slug=="spot").first()
p2.image_url == "http://example.com/adorable.jpg"

View Slide

DELETE FROM DATABASE
# Query to get a Puppy object
rover = Puppy.query.filter_by(slug="rover").first()
# We can delete Rover. Sorry, buddy!
db.session.delete(rover)
db.session.commit()
# Rover is gone!
p2 = Puppy.query.filter_by(slug="rover").first()
p2 == None
# But the local variable still has the old information
# However, all local variables vanish at the end of
# the HTTP request

View Slide

LOTS MORE
SQLALCHEMY DOCS
docs.sqlalchemy.org

View Slide

INTEGRATE FLASK-SQLALCHEMY
from models import db, Puppy
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///puppy.db"
db.init_app(app)
@app.route("/")
puppy = Puppy.query.filter(Puppy.slug==slug).first_or_404()
output = {
"name": puppy.name,
"image_url": puppy.image_url,
}
return jsonify(output)
if __name__ == "__main__":
app.run()

View Slide

OOPS

View Slide

NEED TO CREATE DATABASE TABLES
$ python puppy.py createdb
Database created!
import sys
[...]
if __name__ == "__main__":
if "createdb" in sys.argv:
with app.app_context():
db.create_all()
print("Database created!")
else:
app.run()

View Slide

OOPS AGAIN: NO DATA

View Slide

SEED DATA INTO DATABASE
$ python puppy.py seeddb
Database seeded!
if __name__ == "__main__":
if "createdb" in sys.argv:
db.create_all()
print("Database created!")
elif "seeddb" in sys.argv:
p1 = Puppy(slug="rover", name="Rover",
image_url="http://example.com/rover.jpg")
db.session.add(p1)
p2 = Puppy(slug="spot", name="Spot",
image_url="http://example.com/spot.jpg")
db.session.add(p2)
db.session.commit()
print("Database seeded!")
else:
app.run()

View Slide

/rover
/spot
/lassie

View Slide

pip install slugify
from slugify import slugify
from flask import request
from flask import url_for
@app.route("/", methods=["POST"])
def create_puppy():
# validate attributes
name = request.form.get("name")
if not name:
return "name required", 400
image_url = request.form.get("image_url")
if not image_url:
return "image_url required", 400
slug = slugify(name)
# create in database
puppy = Puppy(slug=slug, name=name,
image_url=image_url)
db.session.add(puppy)
db.session.commit()
# return HTTP response
resp = jsonify({"message": "created"})
resp.status_code = 201
location = url_for("get_puppy", slug=slug)
resp.headers["Location"] = location
return resp

View Slide

LET’S CREATE A PUPPY
$ curl -X POST localhost:5000 -d name=Lassie \
-d url=http://example.com/lassie.jpg -i
HTTP/1.0 201 CREATED
Content-Type: application/json
Content-Length: 26
Location: http://localhost:5000/lassie
Server: Werkzeug/0.10.4 Python/2.7.11
Date: Mon, 25 Apr 2016 22:49:08 GMT
{
"message": "created"
}

View Slide

DYNAMIC
DATA!
Good news:
Bad news:
VERBOSE, 
VIEWS REACH INTO
MODELS

View Slide

db.init_app(app)
@app.route("/")
output = {
"name": puppy.name,
"image_url": puppy.image_url,
}
return jsonify(output)
if __name__ == "__main__":
app.run()
EXAMPLE

View Slide

DAY THREE

View Slide

SEPARATION OF CONCERNS
Database
holds all
internal data
View
communicates
with external clients
Transformer 
converts between 
internal DB resources
and external API resources

View Slide

MARSHMALLOW SCHEMA
from flask_marshmallow import Marshmallow
from models import Puppy
ma = Marshmallow()
class PuppySchema(ma.ModelSchema):
class Meta:
model = Puppy
puppy_schema = PuppySchema()
puppies_schema = PuppySchema(many=True)
schemas.py

View Slide

INTEGRATE FLASK-MARSHMALLOW
from schemas import ma, puppy_schema
db.init_app(app)
ma.init_app(app)
@app.route("/")
return puppy_schema.jsonify(puppy)

View Slide

DEFINE OUTPUT FIELDS
schemas.py
from flask_marshmallow import Marshmallow
from models import Puppy
ma = Marshmallow()
class PuppySchema(ma.ModelSchema):
class Meta:
model = Puppy
exclude = ["id", "slug"]
puppy_schema = PuppySchema()
puppies_schema = PuppySchema(many=True)

View Slide

CREATE A PUPPY
def create_puppy():
puppy, errors = puppy_schema.load(request.form)
if errors:
resp = jsonify(errors)
return resp
puppy.slug = slugify(puppy.name)
db.session.commit()
resp = jsonify({"message": "created"})
location = url_for("get_puppy", slug=puppy.slug)
return resp

View Slide

EDIT A PUPPY
def edit_puppy(slug):
puppy, errors = puppy_schema.load(request.form, instance=puppy)
if errors:
resp = jsonify(errors)
return resp
puppy.slug = slugify(puppy.name)
db.session.commit()
resp = jsonify({"message": "updated"})
location = url_for("get_puppy", slug=puppy.slug)
return resp

View Slide

DELETE A PUPPY
$ curl -X DELETE localhost:5000/spot
{
"message": "deleted"
}

404 Not Found
Not Found
@app.route("/", methods=["DELETE"])
def delete_puppy(slug):
db.session.delete(puppy)
db.session.commit()
return jsonify({"message": "deleted"})

View Slide

LET’S JSONIFY THAT ERROR
{
"error": "not found"
}
@app.errorhandler(404)
def page_not_found(error):
resp = jsonify({"error": "not found"})
return resp

View Slide

$ curl localhost:5000
[
{
"name": "Rover"
},
{
"name": "Spot"
}
]
LIST PUPPIES
@app.route("/", methods=["GET"])
def list_puppies():
all_puppies = Puppy.query.all()
data, errors = puppies_schema.dump(all_puppies)
return jsonify(data)

View Slide

slug = db.Column(db.String(64), index=True)
image_url = db.Column(db.String(128), nullable=False)
age = db.Column(db.Integer, default=1)
BENEFIT: DATA FLEXIBILITY
Modifying the data models just works!
models.py
$ curl localhost:5000/spot
{
"name": "Rover",
"age": 1
}

View Slide

BENEFIT: DATA VALIDATION
Automatic, complete error messages!
$ curl -X POST localhost:5000/
{
"image_url": [
"Missing data for required field."
],
"name": [
"Missing data for required field."
]
}
(“age” is optional, so leaving it off is not an error)

View Slide

FLEXIBILITY &
VALIDATION!
Good news:
Bad news:
BOSS SAYS 
WE NEED USERS

View Slide

DAY FOUR
Flask-Login

View Slide

GET /rover HTTP/1.1
Host: localhost:5000
User-Agent: curl/7.43.0
Accept: */*
HTTP Request
Who is the user? 
No idea.
Authorized HTTP Request
Look up the API key 
to find the user!
HOW DO I LOGIN?
GET /rover HTTP/1.1
Host: localhost:5000
User-Agent: curl/7.43.0
Accept: */*
Authorized: my-api-key

View Slide

USER MODEL
models.py
from flask_sqlalchemy import SQLAlchemy
from flask_login import UserMixin
db = SQLAlchemy()
class User(db.Model, UserMixin):
api_key = db.Column(db.String(64),
unique=True, index=True)
[...]

View Slide

INTEGRATE FLASK-LOGIN
from flask import Flask
from flask_login import LoginManager
from models import db, User
from schemas import ma
db.init_app(app)
ma.init_app(app)
login_manager = LoginManager()
login_manager.init_app(app)
@login_manager.request_loader
def load_user_from_request(request):
api_key = request.headers.get('Authorization')
if not api_key:
return None
return User.query.filter_by(api_key=api_key).first()

View Slide

TEST IT OUT
$ curl localhost:5000/whoami
{
"name": "anonymous"
}
$ curl localhost:5000/whoami \
-H "Authorization: abc123"
{
"name": "Foo Bar"
}
(after creating the User object in the database)
from flask_login import current_user
@app.route("/whoami")
def who_am_i():
if current_user.is_authenticated:
name = current_user.name
else:
name = "anonymous"
return jsonify({"name": name})

View Slide

LOGIN-PROTECTED VIEWS
$ curl localhost:5000/rover

401 Unauthorized
Unauthorized
$ curl localhost:5000/rover -H "Authorization: abc123"
{
"name": "Rover",
"age": 1
}
from flask_login import login_required
@app.route("/")
@login_required
puppy = Puppy.query.filter_by(slug=slug).first_or_404()
return puppy_schema.jsonify(puppy)

View Slide

LET’S JSONIFY THAT ERROR
$ curl localhost:5000/rover
{
"error": "unauthorized"
}
@app.errorhandler(401)
def unauthorized(error):
resp = jsonify({"error": "unauthorized"})
return resp

View Slide

DAY FIVE
Pagination with Flask-SQLAlchemy
Rate Limiting with Flask-Limiter
Swagger documentation with Flask-APISpec
…but I’m out of time!

View Slide

THANKS
David Baumgold
@singingwolfboy
Presenter:
Slides:
Code:
github.com/singingwolfboy/build-a-flask-api

View Slide

Prototyping APIs with Flask

Prototyping APIs with Flask

David Baumgold

More Decks by David Baumgold

Other Decks in Technology

Featured

Transcript