This article was originally posted on Mar 27th 2018 at: https://nickjanetakis.com/blog/flask-libraries-for-building-awesome-real-world-restful-apis
When it comes to building RESTful APIs with Flask, we have a lot of choices in terms of which libraries we could use but I think before we even begin to pick libraries, we need to break down what a typical API will need to do.
- Wiring up your API endpoints
- Serializing and deserializing data
- Validating user input
- User authentication
Part of the appeal for using Flask is you have the flexibility to pick and choose a bunch of libraries that help solve your exact problems. This is great because having a bunch of loosely coupled libraries that do 1 thing very well will allow you to quickly glue things together once you know the basics.
So when it comes to building APIs with Flask, I'm not so much looking for a single library to do everything, because chances are that one library is going to do most things pretty well and do a few things pretty poorly.
This article won't be about taking shots at various Flask API libraries or calling anyone out for doing things in a different way. This article is all about assembling a few high quality / well maintained libraries to build awesome real world API driven applications with Flask.
If you asked me what I would want to do at the code level when building an API, I would come back to you with a list that looks something like this:
- Least amount of boilerplate that you can reasonably ask for while being explicit
- Ability to easily set up RESTful endpoints for CRUD actions
- Quickly and painlessly add non-RESTful endpoints when necessary
- Consistency with Flask for things like referencing routes in
- Easily version and namespace API URLs
- Easily separate and categorize API endpoints with grouped functionality
- White list SQLAlchemy fields when serializing database rows
- Validate fields in a way that feels familiar to WTForms
- Deal with token based authentication that works with headers and also cookies
- Easy to add in "extra" features like rate limiting by sticking to Flask standards
In a perfect world, 1 or more libraries would exist to do all of the above and more. Not only that, but those libraries should be popular and well maintained.
Lucky for us, everything I listed above is available today and you won't even have to write a ton of code because there are 3 libraries that will help us out big time.
If you need a moment to double fist pump in excitement, go for it. I'll wait.
Let's start by tackling how we're going to wire up API endpoints.
I'm a big fan of using Flask-Classful. It's a library to help us easily set up RESTful API route endpoints, and it also makes it really easy to define custom routes when we need it.
If you're an old school Flask developer or happened to be researching API libraries on your own, you may recall seeing a library called Flask-Classy. Flask Classful is the same library, except it's well maintained. The original Flask Classy library has been deprecated by the original author.
Everything route specific in our wish list is covered and more. It offers a number of benefits over using Flask's built in pluggable views. It's a superb choice.
The next thing we need to deal with is serialization and input validation.
Basically, it handles converting JSON to and from SQLAlchemy or Python objects.
For example, we can't just send a raw SQLAlchemy row over HTTP. Instead we first convert it to JSON, and then send that JSON as a response. That's the main purpose of this library.
It also lets us set up these things called schemas. They help us white list and validate input. For example, if one of our fields needs to be a string in between 2 and 200 characters long, we can set that up in our schema.
If it happens to fail the validation then it will return an error with a friendly message. You can sort of compare Marshmallow's validation to the WTForms library.
Lastly, our API needs some way to deal with authentication. In your Flask adventures, you may have heard of Flask-Login? It's an excellent session / cookie based login library.
But since we're dealing with an API now, it's in our best interest to use token based authentication instead of sessions because not all clients support sessions and cookies.
So for that we'll use a popular token format called JSON Web Tokens (JWT).
The Flask-JWT-Extended library handles creating the tokens for us, and also deals with the low level details of reading that token from headers or cookies (for browsers), as well provide a few other goodies like setting up a current_user and a few authentication related decorators.
Basically, it's the equivalent of Flask-Login, but for JWTs. It's really sweet.
The idea here is, other than maybe learning a few basic API specific concepts, there should be no massive barrier of knowledge between building a "regular" Flask app and an "API driven" Flask app.
Both types of applications are Flask apps so you'll be able to reuse a lot of what you already know, assuming you have some experience with Flask already.
So when building APIs with Flask, that's the philosophy I try to live by and the libraries listed above are what I use. I'm extremely happy with the result because there's so little boilerplate and the code is very maintainable.
Do you want a video guided tour on implementing all of the above and more?
Thousands of people have signed up to my Build a SAAS App with Flask course and I often receive feedback requesting to make a new course on building RESTful APIs with Flask.
I recently did something even better. I locked myself in my office for 6 weeks and released 3 hours of video that goes over building an API driven application with Flask, and it's now available for free for anyone who has my existing Build a SAAS App with Flask course.
You can think of it as a companion to the main course where we build up a second application which uses the 3 libraries mentioned in this article and so much more.
Web sockets are also a big component of the this free bonus app. All of this is ready today and you can learn more about the course on the Build a SAAS App with Flask website.
Between the main course and this bonus API app, you'll be well equipped to build many different types of web applications. You'll be a Flask master.