What was the motivation behind apiflask?

[sloria]

Nice work on this! I'm curious to hear about the motivations behind apiflask. What gaps does it fill that existing frameworks don't? I'd be interested to see a comparison with similar projects like apifairy, fastapi, flask-smorest, flask-resty, flask-restx, flask-rebar, etc.

[greyli]

Hi Steven, this project will never exist without the marshmallow-code projects you created, thank you!

In a word, I try to provide an elegant (act as a framework, no need to instantiate additional extension object) and simple (more automation support for OpenAPI) solution for creating web APIs with Flask. Here is a quick summary of the differences:

The differences between APIFlask and similar projects

A natural order of view arguments

By acting as a framework on top of Flask, it can overwrite the way Flask passes path args to view functions from keyword arguments to positional arguments.

Assume a view like this:

@app.get('/<category>/articles/<int:article_id>')
@input(ArticleQuerySchema, location='query')
@input(ArticleInSchema)
def get_article(category, article_id, query, data):
    pass

With APIFlask, you can accept the arguments in a natural way (from left to right, from top to bottom):

def get_article(category, article_id, query, data)

With APIFairy, Flask-Smorest, or Webargs, you have to do this:

def get_article(query, data, category, article_id)

I achieve this by overwriting Flask's Flask.dispatch_request method at this line (I'm not sure if there is a better solution for this).

Route shortcuts

APIFlask added some route shortcuts (app.get(), app.post() , etc) for app.route(..., methods=['GET/POST...']).

P.S. I proposed to add these to Flask itself, it finally supported in Flask with pallets/flask#3907.

More automation for OpenAPI generating

I tried to add more automation support in APIFairy (miguelgrinberg/APIFairy#10) but failed.

Besides adding an auto summary for the view function, APIFlask also does the following:

• Add success response (200) for a bare view function that only uses route decorators.
• Add validation error response (400) for view functions that use input decorator.
• Add authentication error response (401) for view functions that use auth_required decorator
• Add response schema for potential error responses of view function passed with doc decorator. For example, doc(responses=[404, 405]) (I'm considering rename the responses argument to errors or error_responses, what do you think?).

These behaviors can be changed with related configurations.

More features compare with APIFairy

I'm not very familiar with Flask-RESTy, Flask-RESTx, and Flask-Rebar. Compare to APIFairy (it seems similar to Flask-Smorest) I added these features in APIFlask:

• Add a doc decorator to allow set the OpenAPI spec for view functions in an explicit way.
• Support more OpenAPI fields (all fields from info, servers, response/requestBody/parameters example, path deprecated, etc).
• Support to customize the API documentation config and CDN URLs.
• Return JSON response for all HTTP errors and Auth errors as default.

The differences between APIFlask and FastAPI

I have to admit, I know little about FastAPI other than the introduction on its README. The differences I know so far:

• FastAPI builts on top of Pydantic and Starlette, while this project builts on top of Flask and marshmallow-code projects (Marshmallow, Webargs, APISpec).
• APIFlask is built on top of Flask, thus it's compatible with Flask extensions.
• FastAPI mixed docs translation in one repo and mixed questions in the issue tracker (Moving docs translations into separate repository tiangolo/fastapi#2487), while APIFlask will avoid this. Maybe FastAPI takes this as a way to grow the community, but in my opinion, it will lead to an unhealthy maintenance status.

I will try to learn more about FastAPI, then I will update this section.

---

Update:

Added a new chapter based on the summary above (Comparison and Motivations).

[greyli]

Good idea, I will add this to the docs.

[lafrech]

Hi @greyli.

Among the frameworks quoted here, I believe flask-smorest (which I maintain) is the closest to APIFlask. They rely on the same marshmallow libs. They even have common additional features (at least pagination).

I contacted Miguel Grinberg about API Fairy and he told me he did it for his own need with opinionated choices and shared it without the will to let it grow.

I had a quick look at your code and I totally understand why you started from scratch rather than using mine. You must have a good knowledge of Flask so you know very well what you're doing and you did it clean right away, while flask-smorest is the result of clumsy iterations over a code base started back when I didn't know Flask that much, and I'm still carrying the burden of the past in some places, I guess. And still no typing support.

There are definitely things worth borrowing from APIFlask (security, args order,...).

When I get the time, I'd like to try to port one of our apps to API Flask, see how it goes and what could be missing.

I hate work duplication so I'd be happy to share the effort with you if our libs could be merged somehow.

[greyli]

Hi @lafrech,

Thank you for the feedback. Yes, I read the documentation of flask-smorest quickly when I write the draft summary above and found out that APIFairy has similar APIs with flask-smorest.

When I get the time, I'd like to try to port one of our apps to API Flask, see how it goes and what could be missing.

Cool, I'm looking forward to your review and feedback.

There are definitely things worth borrowing from APIFlask (security, args order,...).
I hate work duplication so I'd be happy to share the effort with you if our libs could be merged somehow.

That's would be great, I do need some help. Before it happened, feel free to borrow anything from APIFlask, and I will also try to get some inspiration from flask-smorest when I try to add class-based-view support, pagination support, etc.

[lafrech]

I didn't get the time to try that yet.

One feature I'd be missing is the ETag feature. I'm not very proud of its implementation in flask-smorest.

I try to keep features separated using mixin classes. None of them is optional, ultimately, the Api class inherits all mixins, but at least I try to separate concerns.

The ETag feature is hard to separate because one of its key interests, at least performance-wise, is to be able to compute the ETag either before of after serialization avoiding to execute the serialization twice for a single request when possible, so it's kind of entangled in the serialization (response) feature. I may also be underusing Flask/Werkzeug ETag-related features.

I couldn't come up with a nicer implementation and at this point, I don't see how to achieve this outside of the serialization feature, so I'm not sure I could add it to another framework. Or it would involve more manual work from the user and potentially a performance impact if the ETag computation requires the serialization of the payload.

[greyli]

It's Ok, there is no rush. In the next version (0.5.0), I will focus on adding class-based view support. The ETag and pagination feature may be in 0.6.0 and I will try to find a better implementation. We can discuss these three key features that flask-smorest has then if you have free time.