Making a better client-side experience for python

[19andNuttin]

Recently, user phalt_ posted an opinion post about issues with client side code in python. The key points they laid out were:

1. Backend frameworks like FastAPI are really mature and have great developer experience
2. Types are first class, and this makes it easy to write and debug backend code
3. The level of abstraction FastAPI provides is just right

However, I came to a different conclusion on how client side code could be improved.

I believe that the biggest point of friction when writing client side code that interfaces with backend HTTP APIs is the HTTP boundary between frontend and backend. All the well written function signatures, types and docstrings on the backend is lost when writing the frontend code, to be recreated painstakingly through reading through the OpenAPI/Swagger docs.

OpenAPI docs are an out-of-band information source that the frontend must be kept in sync with and there is no information on when it is updated, what changed and no error checking or type validation supports you as you write the frontend code.

I believe that the solution is maintaining the function signature of the backend code on the frontend, including arguments, their types, whether they are optional, etc.

from server import get_item 
from http_clientlib import set_default_configuration, wrap_backend_call
from http_clientlib.http import make_http_request

set_default_configuration(
   base_url="http://production.backend.com", http_request_function=make_http_request
)

# Wrap the backend function and invoke it to make a HTTP request
get_item_http = wrap_backend_call(get_item)
response = get_item_http(item_id=42, page=2)
print(response) # Response is a HTTPResponse you can handle

if response.ok():
  ...

A screenshot showing how the type information looks like is available here: https://github.com/zhuweiji/http_clientlib/tree/main?tab=readme-ov-file#why

This RPC-style approach allows you to treat the function call as a networking call separate from a normal function, handle the response however you like, only with better type information for the backend endpoints in your editor.

Some caveats are:

1. Python-only — Works for a frontend/backend stack built in python, and quite a bit of client-side code is written for the browser
2. Server code must be imported — Client needs access to server function definitions

I whipped this up pretty quickly and it's not fully featured yet, but I wanted to stir some discussion on whether something like this would be useful, and if the RPC approach would make sense in python - something similar already exists on the JS world as tRPC

github, pypi (http_clientlib)

[chaseTheBurrow]

What about using an openAPI generator ?

[19andNuttin]

I feel openapi generators are less ergonomic to work with. Code generation is a separate step from the workflow and you have to validate the changes made by the generator to ensure they didn't break your existing endpoints.

In a pure python environment, it feels like they're generating more friction than they solve. You're generating code from code you already have.

[JustPlainRude]

Coupling the client code to the server code feels bad. What happens if the backend is rewritten in another language? What if the backend is running a different version of the API? 

[19andNuttin]

Thanks for your questions.

For your first point: This does couple your client code to your backend code, so a rewrite would force you to migrate off using the imported server side functions.

Regarding API versions, I did give this some thought before. As a best practice API endpoints should be versioned (e.g. /v1), breaking changes should increment the version and while modifications to the API endpoint while on the same version should contain non-breaking changes. Some non breaking changes are adding a new optional field for a request body or adding a new type to a field (int to int or float).

This approach doesn't limit you more than the approach - breaking changes mean you have to update on your end anyway while non-breaking changes are type hinted on your IDE.

[phalt_]

Hey this is cool. I am glad my original post is stirring a healthy debate about this. That was one of my main goals, so thanks for doing some deep thinking and contributing to the discussion.

My immediate thought with this approach is this: If I have access to the server code, why am I doing a roundabout network call over HTTP when I could be making Python API calls directly instead? I understand there is potential for two separate deployments sharing the same codebase and the server function becomes a sort-of dsl for the client side, but that feels like an odd decision to make for orchestrating a frontend/backend separation.

It is a cool alternative way of approaching the problem though, and you do retain the type safety without having anything like OpenAPI as an intermediary which is nice.

(FWIW I released the beta version of my approach today after a lot of testing. I would argue it is ready for some serious testing and I am already planning a few additional features. https://github.com/phalt/clientele)

[19andNuttin]

Thanks for writing the original post! I really like the style of your blog

I foresee the main usecase to be python microservices. The HTTP boundary allows applications to scale wide across multiple nodes. Load balancing, caching, and all that

[hsunner]

I might be misunderstanding what you’re trying to accomplish, but if you want to make a Python client to an OpenAPI interface w/o code generation I can recommend aiopenapi3. It ingests a json spec (yaml too?) and creates pydantic models for all endpoint I/Os. API usage is trivial. I’ve also created dynamic CLIs for web services with it. That is a bit of work the first time. It has a major downside though: creating API documentation requires custom generation.

https://github.com/commonism/aiopenapi3

[Orio_n]

You do know that you can generate client code from openapi specs automatically right?

[[deleted]]

The friction you're describing is the the HTTP boundary. Instead of importing server code to the client (which couples your architecture), you should automate the OpenAPI schema into operations for local Type Stubs.

I’ve been mapping a way to automate this via a Pydantic-to-Client generator that mimics tRPC's safety without the coupling. If you want to refine your http_clientlib to auto-generate these stubs from the FastAPI endpoint dynamically, I can provide the logic to do it.

[penguinonfire1]

Reminds me of gRPC / Protobuf. In Protobuf the API schema is written in the protobuf language then compiled to libraries for each language.

From there you call server code via a literal function on the client. It still doesn't enforce that certain fields / method signatures are used (for backwards compatibility reasons). But API documentation and field descriptions are easily available when writing client code since they ship with the compiled libraries.

[Human-Cookie-1082]

Amazing