BUILDING BEAUTIFUL REST APIs

with Flask, Swagger UI and Flask-RESTPlus

Michał Karzyński • EuroPython 2016

 ABOUT ME

• My name is Michał Karzyński (that’s Polish for Mike)

• I blog at http://michal.karzynski.pl

Short URL: karzyn.com

• I wrote a book for Linux admins, I write code in Python and JavaScript

• I’m the tech lead of a Web UI team at

 WHAT IS A WEB API?

Web (JavaScript)
API
(JSON)

Server

(Python)
Phone (Swift, Java)
 WHAT IS A REST API?
REPRESENTATIONAL STATE TRANSFER

A clever way to use HTTP to build APIs.

 ANATOMY OF HTTP

Method Path Query Status Code

Headers Headers

Body Body

Request Response
 GET ?search=Moby Dick
POST
PUT /api/books Cookies… 200 OK
DELETE
404 Not Found

Method Path Query Status Code

Headers Headers

Body Body

Request JSON Response

 Method Path Query
Headers

REST CONVENTIONS Body

GET PUT POST DELETE

Collection
 List books New book

/books

Item
 Display book Update book Delete book

/books/123

Controller Borrow book

/books/123/borrow
 FLASK

flask.pocoo.org
 FLASK-RESTPlus
• define and document endpoints

• validate input

• format output (as JSON)

• turn Python exceptions into HTTP responses

• minimise boilerplate code

flask-restplus.rtfd.io
• generate interactive documentation (Swagger UI)
Demo
OPEN API FORMAT
 OPEN API SPECIFICATION
• Standard language to describe REST APIs

• Open source (Linux Foundation)

• Tools:

• Swagger UI

• Swagger Editor

• Code generators

• Initiative with many powerful members

openapis.org swagger.io
 OPEN API SPECIFICATION
• Standard language to describe REST APIs

• Open source (Linux Foundation)

• Tools:

• Swagger UI

• Swagger Editor

• Code generators

• Initiative with many powerful members

openapis.org swagger.io
Method Path Query

Headers

Body

Request
 Method Path Query

REQUEST METHOD Headers

POST /api/books/123/borrow?when=today Body

from flask_restplus import Resource

@api.route('/<int:id>/borrow')
class BorrowBookController(Resource):



def post(self, id):

""" Borrow book from library.



Allows the current user to borrow
the book out of the library.

"""

...
return {'message': 'OK'}
 Method Path Query

REQUEST METHOD Headers

POST /api/books/123/borrow?when=today Body

from flask_restplus import Resource

@api.route('/<int:id>/borrow')
class BorrowBookController(Resource):


 class Resource:

def post(self, id):
 

""" Borrow book from library.
 def get(self)...


 def post(self)...

Allows the current user to borrow def put(self)...

the book out of the library.
 def delete(self)...

"""
 def patch(self)...

... def options(self)...
return {'message': 'OK'} def head(self)...

 Method Path Query

REQUEST METHOD Headers

POST /api/books/123/borrow?when=today Body

 Method Path Query

REQUEST METHOD Headers

POST /api/books/123/borrow?when=today Body

 Method Path Query

REQUEST PATH Headers

POST /api/books/123/borrow?when=today Body

@api.route(‘/books/<int:id>/borrow’)

@api.route('/articles/<title>')

@api.route('/wiki/<path:wikipage>')

@api.route('/values/<float:value>')

@api.route('/object/<uuid:identifier>')
 Method Path Query

REQUEST PATH Headers

GET /api/book/123/borrow?when=today Body

 Method Path Query

QUERY ARGUMENTS Headers

GET /api/books?page=1&per_page=10 Body

from flask_restplus import reqparse




pagination = reqparse.RequestParser()

pagination.add_argument('page', type=int, required=False,
default=1, help='Page number')

pagination.add_argument('per_page', type=int, required=False,
choices=[10, 20, 30, 40, 50])

 Method Path Query

QUERY ARGUMENTS Headers

GET /api/books?page=1&per_page=10 Body

from flask import request


from flask_restplus import Resource



@api.route('/')

class PostsCollection(Resource):



@api.expect(parsers.pagination)

def get(self):

args = pagination_arguments.parse_args(request)

page = args.get('page', 1)

per_page = args.get('per_page', 10)

...
 Method Path Query

QUERY ARGUMENTS Headers

GET /api/books?page=1&per_page=10 Body

 Method Path Query

REQUEST BODY (JSON)
 Headers

API MODELS Body

blog_post = api.model('Blog post', {


'title': fields.String(description='Article title'),

'body': fields.String(description='Article content'),

'pub_date': fields.DateTime,

'category_id': fields.Integer(min=1),

})

@api.expect(blog_post)

def post(self):

...
 Method Path Query

REQUEST BODY (JSON)
 Headers

API MODELS Body

 Method Path Query

API MODELS
 Headers

INHERITANCE AND NESTING Body

category = api.model('Blog category', {


'id': fields.Integer(description='The unique id of category'),

'name': fields.String(description='Category name'),

})



category_with_posts = api.inherit('Blog category with posts', category,
{

'posts': fields.List(fields.Nested(blog_post))

})
Status Code

Headers

Body

Response
 Status Code
Headers

RESPONSE STATUS CODE Body

@api.route('/<int:id>')

@api.response(404, 'Post not found.')

class PostItem(Resource):



@api.response(204, 'Post successfully deleted.')

def delete(self, id):

"""

Deletes blog post.

"""

delete_post(id)

return None, 204
 Status Code
Headers

RESPONSE STATUS CODE Body

 Status Code
Headers

RESPONSE BODY (JSON) Body

blog_post = api.model('Blog post', {

...

'category_id': fields.Integer(attribute='category.id'),

'name': fields.String(attribute=lambda x: x._private_name),


})

@api.marshal_with(blog_post)
 @api.marshal_list_with(blog_post)

def get(self):
 def get(self):

... ...
 EXCEPTION HANDLING

from sqlalchemy.orm.exc import NoResultFound




@api.errorhandler(NoResultFound)

def database_not_found_error_handler(e):

log.warning(traceback.format_exc())

return {'message': 'A database result was not found.'}, 404
INERACTIVE
DEBUGGER
 from flask import Flask

from flask_restplus import Resource, Api



app = Flask(__name__)

api = Api(app)



@api.route('/hello')

class HelloWorld(Resource):

def get(self):

return {'hello': 'world'}



if __name__ == '__main__':

app.run(debug=True)
Demo code and article available on my blog:

karzyn.com

THANK YOU