Introduction
Note for frequent readers: this blogpost is written in English since I want to share this post with the fastai community
Hello everyone,
In this post I won’t discuss Flutter as you are used to, but I will go back to my roots: Python. Python is an extremely convenient lanuage since it has hundruds of usefull packages which make you more productive. Here, I will share two awesome packages nbdev1 and FastAPI2. Furthermore. I will show you how to combine these two packages to create an awesome documented web-API.
FastAPI
FastAPI3 is a package that is useful to create a high performing and automatically documented web API.
The FastAPI documentation is better in explaining its greatness but I will try to summarize it.
FastAPI is based on two packages. Firstly, Starlette4, a lightweight Asynchronous Server Gateway Interface (ASGI) framework. Secondly, Pydantic5, a data validation package using Python type annotations. Due to the async capabilities its fast and do to Pydantich and Python’s type annotations it helps you speed up your API development and it helps you preventing errors. And, as icing on the cake, it autogenerates API documentation (OpenAPI/Swagger and Redoc). However, it does not cover code documentation, which is necessary to cooperate efficiently with other developers. That is one of the strengths of using Notebook development with nbdev.
nbdev
I think that most Python developers have use Jupyter Notebooks. And I also think that the majority of that group liked the experimental workflow that Notebooks facilitate. However, developing in a Notebook has many pitfalls such as: * Since Notebooks are JSON files with changing Metadata it is hard to use it with version control practices * It does have reproducibility issues (for example, running code cells in the correct order) * Difficult to test
But fear not, nbdev6 is our saviour.
Nbdev improves developing in Notebooks by extracting code into Python modules (which already solve the Notebooks version control horrer and order of code execution)! Additionally, using Notebooks you can let your creative genius fly and do all the exploratory development you want since your findings are easily integrated in a module. Lastly, your Markdown cells is used to create documentation automatically! In my opinion, this solves a massive problem in software engineering, namely proper code documentation. You are now able to explain your code choices with text, images, links, graphs you name it!
For example, whenever you optimize a piece of code, you can now document it together with your code by showing a graph of the old vs new situation.
In theory, when combining FastAPI and nbdev you can now create code which is fully documented for your fellow programmers and an API which is documented by autogenerated FastAPI docs. But does it work in practice?
Combining FastAPI and nbdev
The answer is YES! In this Github repository7 I have created a small and simple proof of concept. As you can see in the Notebooks, I have documented how to use the repository in the Notebooks itself.
I think it is amazing to be able to create a fast web API using an experimental workflow with the ability to add proper documentation.
Lastly, you can even test your endpoints if you alter nbdevs CI Github Action slightly8. With the small change, it starts the web API in the Github action before running the tests :).
I want to encourage you to give nbdev a try for your next project. You can share your experiences and ask question on this forum9.
Thank you for reading and have fun programming!
Mees