This is the first part of a two-part series. In this post, I will introduce Flask-RestPlus and demonstrate how to start organising APIs around its simple REST-based conventions. Next time, I will address the topic of request/response marshalling (serialisation) and validation.
Well, if you run your Flask app and click on the login button on your welcome page, you should be redirected to Spotify’s authentication page! ? The authentication page should look something like this. Once you fill in your Spotify details, you should then be redirected to. There's also a SongPal app that takes care of both music playback and the SRS-X9's settings. Sony has other wireless speakers, the smaller SRS-X5 and SRS-X7, which also play nice with Spotify Connect.
A seasoned Spring developer, I felt a bit uneasy when designing and future-proofing a Flask-based API for the first time. I have recently started using Python way beyond my original intention to just play with data, and found Flask to be a super-easy micro-service alternative to Spring Boot or Ktor. The one thing I was really concerned about, was making sure that the API request/response format was standardised (think, providing a Swagger schema), well-documented, and validated. While working with Java, much of this would come straight from the compiler itself, due to the static-type nature of the language. When you combine this with a couple of great libraries like Jackson and SpringFox, the API communication gets documented and validated with minimal intrusion to the actual code. In Python, this would require tedious
if-else checks all over the place .. or so I thought.
Flask-RestPlus to the Rescue
Unlike Django, Flask does not come with batteries included, but there is a whole ecosystem of open-source libraries and extensions contributed by the community. One of these is called Flask-RestPlus and it is the absolute dream-come-true for every Flask API designer. Flask-RestPlus is a Flask extension library, and as the name suggests, it helps ease the building of structured RESTful APIs with minimal setup, and encourages best practices. Flask RestPlus follows certain conventions, but does not insist on them, the way Django does. In a way, Flask-RestPlus tries to help organise a growing Flask project, but without it losing its minimal overhead, which is the greatest charm of Flask.
The goal of this series is to start with a simple Flask app, and try to address the following points with a bit of Flask-RestPlus at a time:
Demo App
Let's start with a simple Flask-based API for a conference management application:
Installing Flask-RestPlus is easy
![]()
Let's simply introduce an Api object for now, try to wrap our app instance with it, replace the routing decorators, and see what happens:
As soon as the app starts, we will get the following error:
This is because if you want to use RestPlus for some of your Flask functions, you have to enclose them in a scoping class. Not only that, but inside the enclosing class, you should name your methods, corresponding to the HTTP methods that REST is based on: GET, POST, PUT, and DELETE:
Before anyone starts objecting, let me explain why this is helpful. Flask-RestPlus uses the Flask concept of 'Pluggable Views' to introduce
Resource (as in, REST resource).
Flask App Spotify Subscription
Let's be honest. While most Flask applications start simple, many of them outgrow the initial idea, and cramming several handler functions in the main module scope quickly becomes a mess. This is why Flask Blueprints exist to help split common functionality into multiple modules.
Flask-RestPlus makes great use of Blueprints too, as I will demonstrate later, but Resources go one level of granularity further. A Resource class can have multiple methods, but each one should be named after one of the accepted HTTP verbs. What if you need more than one
GET or POST method for your API? Well, create multiple Resource classes and put each method in the corresponding resource class. It might look a little overwhelming at first, coming from the cut-the-boilerplate nature of Flask, but with a bit of playing around, it won't be a brainer at all, and it will pay off tremendously in the long run.
Let's see how our tiny app will look after the transformations:
Spotify web player download chrome. With this tiny bit of overhead (if you even consider this any overhead at all), you get so much in return. Start the app and point to http://localhost:5000. You will see that the index page has turned into a Swagger UI, which shows the already defined API endpoints, neatly organised into categories (namespaces):
This is great for documenting, playing with, and sharing you API schema around. Yet, this is by far not the only thing that Flask-RestPlus does for you. It goes beyond simply documenting the API, in ensuring that the API is compliant with the schema. Put simply, Flask-RestPlus makes sure that if certain request parameters are marked as mandatory, or if request/response models are supposed to have a certain structure, those are checked and validated at runtime. In my opinion, this is real advantage of Flask-RestPlus, sitting on top of a Flask application. The current example is too simple to demonstrate the real power of request/response marshalling and validation, but both will be throughly described in Part 2.
Flask App Spotify LoginNamespaces
Namespaces are optional, and add a bit of additional organisational touch to the API, mainly, from a documentation point of view. A namespace allows you to group related Resources under a common root, and is simple to create: Spotify premium google home free.
To bring certain Resources under a given namespace, all you need to do, is to replace
@api with @ns_conf . Notice also that the name of the namespace replaces the name of the resource, so endpoints can simply to refer to / , instead of copying the name of the resource time and again:
One will notice afterwards that the Swagger UI display has changed too, to reflect the namespacing:
Blueprints
Flask Blueprints are a popular way of designing modular applications. The same applies to Flask-RestPlus. The production version of our application will certainly outgrow the four endpoints we started with. There might be other resources, or at the very least, you might want to move to move your API away from the root of your app. Both cases are a perfect candidate for a Blueprint. Let's move all of our API endpoints under
/api/v1 , without touching the routes of even one of them. This example is coming straight from the Flask-RestPlus documentation, and is illustrative enough to help close this chapter of the journey:
Create a Blueprint the usual way, and instead of wrapping our app instance with the RestPlus API, we will wrap the Blueprint instead. This way, independent of our app, we are free to move our API part into a different module: (e.g. Combine playlists spotify app.
blueprint/api.py ).
Flask App Spotify Account
This leaves only a tiny bit of bridging code to introduce the Blueprint to the main app, and set the URL prefix. The next time you start your app, the API endpoints will be accessible only under the specified URL prefix (
/api/v1 ):
Last but not least, it is always a good idea to move the Swagger UI documentation away from the root. As in everything else in RestPlus, this part is extremely ease, too. You can override the default location by passing an additional parameter to the initialiser:
Flask App Spotify App
This sums up the first part of my series. I hope that it was informative, and will help you structure your Flask-based REST APIs better in the future. Till next time!
Further ReadingComments are closed.
|
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |