API Starter Kit

Python Flask API — Starter Kit and Project Layout

APIs changed the way we build applications, there are countless examples of APIs in the world, and many ways to structure or set up your APIs. Today we will discuss how I use Python and Flask to build and document REST APIs that scale to every need.

As usual, I’m providing sample applications, for this case a starter kit for everyone to use and build upon, here is the link to the final code we will review today.

Before we start with code…

Let’s first discuss the project dependencies, why each of them is necessary, and how it can benefit our project.

  • flask: Flask is a micro web framework which has a minimal footprint compared to others like django, and allows us to select which components and modules we want to integrate with it. Flask is highly reliable and performant.
  • flasgger: It’s a module that helps us integrate swagger docs to a flask API.
  • flask-marshmallow: Object serializer, ideal for parsing and dumping JSON data in and out of our API.
  • apispec: Required for the integration between marshmallow and flasgger.

Project Layout

We will start discussing how the project layout looks like by taking a look into the folder structure:

I think that the folder structure is self-explanatory, but let’s look at it part by part API Module.

The API module will host our application code, from models, routes, schemas and controllers if needed (though I usually don’t create those).

  • The models are the data descriptor of our application, in many cases related to the database model, for example when using sqlalchemy, though they can be any class which represents the structure of our data.
  • The routes are the paths to our application (e.g. /api/home or /api/users) and it's where we will define the route logic, data retrieval, insertion, updates, etc.
  • The schemas are the views (serializers) for our data structures. We should have at least one schema per model. The schemas will have it's own definition as we will see later.

This is an example of the most basic definition for a route, let’s take a look into it line by line:

Blueprint creation, I like to separate the application in different blueprints, where I provide at the beginning of the file the parent route, in this case /api and all the subsequent routes will be relative to this one.

Next is the route itself, in this case we first define the route for the application, there are several ways to do this, and they are very well covered in the flask docs. Right after the route definition we need to provide information for the swagger documentation. I’ve set an example where we define the response object, and the endpoint description as string literals, but there’s more you can do if you follow the official documentation.

Then we need to place the code for our application, to eventually return an object from the API. To serialize the object we use our schemas as can be seen on the code.

The schemas are a very important part of this setup, and they are covered in detail in the flask-marshmallow documentation, but in essence a schema is a class that defines the properties and relationships among models and others in so that python can serialize the objects.

Here are some sample schemas from my blockchain code.


As with any other application, tests are super important, and I could have an entire post discussing why. But here we will keep it simple. For tests I’m simply using unittest module from python, and I try to build tests for each component. Here is an example for our home route:


Finally, we need the place where we glue it all together, and we create our python API

In the file app.py we define the python flask application. Inside the create_app function you would need to specify your app name for the swagger configuration, each one of your blueprints, any other initialization step such as the db connection, all that would happen here, and there are good examples in the flask quick starter.

Environment Set Up

Swagger Doc UI Example

I hope this tutorial and project help you build your next API and as usual please let me know if you have any other ideas on twitter at @livecodestream, or simply create an issue, or a PR on the github project.

Thanks for reading!

Originally published at https://livecodestream.dev.

I’m an entrepreneur, developer, author, speaker, and doer of things. I write about JavaScript, Python, AI, and programming in general.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store