1. 6

Hey lobsters. I wrote this a while ago to scratch my own itch. I think defining api specifications by manually entering extra meta-data is non sense. The definitions are already there, in the code. I wrote this tiny python module to materialize this idea. Parsing input data and specifying input data, are two tasks that ultimately build on the same single source of truth.

This consists of a single annotation and takes 5 minutes to master. You can also read the entire source code in a few minutes.

These 200 lines of python code have been very useful to me, maybe they can save you time too.

  1.  

  2. 2

    Where does flask sit in the spectrum of backends these days? I used to use it all the time, but I kinda feel like it’s sweet spot was making quick and dirty backends, and these days you might be better served by (eg) hasura (or Postgraphile, or PostgREST), which will have you up and running in no time.

    And for anything “big” there’s obviously Django, or Django REST Framework, with all the batteries included (admittedly not so attractive if you like SQLAlchemy a lot more than Django’s ORM, as I do).

    1. 2

      Where does flask sit in the spectrum of backends these days? I used to use it all the time, but I kinda feel like it’s sweet spot was making quick and dirty backends, and these days you might be better served by (eg) hasura (or Postgraphile, or PostgREST), which will have you up and running in no time.

      It is by and large the most popular micro http framework for python. Personally I have used perhaps 10+ such frameworks, half of which before flask even existed. But a combination of being actively maintained and well documented plus having a sizable ecosystem, have put flask in the preference of most developers that want a quick way to write an HTTP service. In fact, django users tend to maintain a large django project while flask lends itself better to the use case of a few or several distinct http server apps. So I am not sure django is even more popular than flask.

      EDIT: it’s not. Flask is now the #1 python web framework popularity wise. https://testdriven.io/blog/django-vs-flask/

      Postgrest and similar are not a solution for most people. You are assuming that a quick and dirty backend is just exposing a database as REST, while this is rarely the case. Not many REST services talk only to a relational database. Most will [also] do one or more of:

      • writing or reading to/from filesystem
      • perform http requests
      • shell out a command
      • send an email
      • talk to other data stores (redis, another relational db, kafka, cassandra, etc.)
      • modify the state of in memory data
      • output hard coded information
      • run an algorithm

      Don’t get me wrong, I am huge fan of PostgREST, but to my experience, there are very few developers out there that would go for writing their rest APIs in PL/pgSQL, most probably don’t even know what that is. I have never encountered a single situation where one would be fine just by exposing a bunch of tables as Rest endpoints. More evolved logic is always necessary.

      And for anything “big” there’s obviously Django, or Django REST Framework, with all the batteries included

      There’s nothing obvious about picking django for that purpose if you ask me. Django poses many portability and scalability issues when compared to micro frameworks. Furthermore, its philosophy of owning all aspects is your system are objectively bad architecture: why should you database migration and schema be owned by a web application? Why do most things require an environment to be set up and import many django packages so you loose the possibility of using them as a stand alone python package? Why insisting on hacks like form objects as the primary way to submit data at this day and age where most websites won’t even work without javascript? Why encouraging people scheduling tasks asynchronously on a an application that is essentially a web server?

      admittedly not so attractive if you like SQLAlchemy a lot more than Django’s ORM, as I do

      Or if you don’t like/need ORMs at all.

      1. 2

        You are assuming that a quick and dirty backend is just exposing a database as REST, while this is rarely the case.

        I actually do think this is how most Flask projects start: by RESTifying some CRUD operations on a database. You make a good point with the rest of the items on that list, though.

        there are very few developers out there that would go for writing their rest APIs in PL/pgSQL

        This is absolutely true, and I certainly wouldn’t recommend doing it that way. If you’re at the point of writing logic then use a proper language for that. I think people who haven’t tried something like Hasura + Postgres might underestimate how much you get out of the box there - provided what you’re looking for is generally CRUDlike.

        There’s nothing obvious about picking django for that purpose if you ask me

        Totally agree - I’ve tried to pick-up Django a few times, and there’s so much going on there that I’ve just never stuck with it, and have usually ended up whipping up something in Flask instead. These days I’d probably look to a Typescript application, though.

    2. 1

      Isn’t it called OpenAPI for a few years now? Or does this target a much older version of the specification?

      1. 1

        It targets apispec v2 which I believe it’s still more common than v3. But that would still be called OpenAPI though. I didn’t put much thought on the name, “swagger” is just catchier than “OpenAPI”, it got more swag maybe? :D

        I do include swagger ui, so the name is still somehow accurate as it also includes tools, and not just the apispec.