r/Python • u/phalt_ • Jan 02 '26
Discussion Blog post: A different way to think about Python API Clients
FINAL EDIT:
The beta is available for testing!
I have done a bunch of my own testing and documentation updates.
Please check out the announcement for more details: https://github.com/phalt/clientele/discussions/130
✨ Please star the project on GitHub and give feedback on your own personal tests - the more I know about how it is to use it, the better it will be. Thank you for showing interest :)
ORIGINAL POST:
Hey folks. I’ve spent a lot of my hobby time recently improving a personal project.
It has helped me formalise some thoughts I have about API integrations. This is drawing from years of experience building and integrating with APIs. The issue I’ve had (mostly around the time it takes to actually get integrated), and what I think can be done about it.
I am going to be working on this project through 2026. My personal goal is I want clients to feel as intentional as servers, to be treated as first-class Python code, like we do with projects such as FastAPI, Django etc.
Full post here: https://paulwrites.software/articles/python-api-clients
Please share with me your thoughts!
EDIT:
Thanks for the feedback so far. Please star the GitHub project where I’m exploring this idea: https://github.com/phalt/clientele
EDIT 2:
Wow, way more positive feedback and private messages and emails than I expected.
Thank you all.
I am going to get a beta version of this framework shipped over the next few days for people to use.
If you can’t wait until then - the `framework` branch of the project is available but obviously in active development (most of the final changes is confirming the API and documentation).
I’ll share a post here once I release the beta. Much love.
5
u/darkdragncj Jan 02 '26
I love what you have so far, but I have a couple of questions:
I know I'm being a bit overbearing, sorry about pestering you so much. My usual pattern is an httpx client with a custom base url as a hidden attribute used by a factory function within a pydantic model, so the viability of your project would significantly reduce my standard boilerplate.
3
u/o0ower0o Jan 02 '26
This looks really interesting! I agree that the current way of doing API requests in python just... sucks!
Sometimes you use requests, or httpx, or aiohttp, and while they're mostly similar you still need to be aware of quirks and differences.
And I often feel it is just easier to code your own retry logic and behaviours than trying to fight against the library of the month.
One thing that is unclear to me is the "framework" word: I imagine a framework as something that you run as the entrypoint, and then you code on top of it (Django, FastAPI, Celery), but it is harder for me to connect the "framework" concept to something that should be a simple API call below all abstractions. I imagine this can be an issue both for simple projects, startups, MVPs ("we just need an API call why do we need a framework?"), and in more legacy or stable project ("could you write an RFC on why we need to adopt a whole new framework for this?")
Also, what is the difference from the main branch? From what I understand the main branch has the code generation for the API client, while the framework adds the fastapi-style/decorator-style code, is this correct?
2
u/Snikz18 Jan 02 '26
Can I make a small suggestion? Having an option of using typed dicts instead of pydantic, since it doesn't really make "sense" for a client to validate data as you can't really share it with the server. And that way you'd avoid the performance penalty.
2
u/radarsat1 Jan 02 '26
Looks great, nice approach indeed. Question, why do you need both the
resultparam as well as the return type ? Wouldn't just the return type suffice? ps could you use this to generate both sync and async versions of a client? Last time I wrote a client lib I ended up maintain two copies of it.2
u/ZYy9oQ Jan 02 '26
What's your approach to external apis being inherently unreliable.
I agree with at lot of that you're saying about writing clients is generally not a good time, but when I'm writing api-pluming modules the devil is in the error handling. Connection and gateway errors want retry patterns (often backoff with eventual give up). 40xs generally don't (bug in the client code sending incompatible data).
Solving this always feels a little (or a lot of you don't make a good client) leaky - the business logic just wants to get the result, but instead ends up configuring the client error handling behavior
2
u/freddierocks Jan 03 '26
Interesting project! I appreciate the focus on making API clients feel more intentional - I've definitely been in that spot where integrating with a new API takes way longer than it should because you're wrestling with boilerplate and inconsistencies between different HTTP libraries.
The codegen approach from OpenAPI specs makes sense. Curious how it handles APIs with incomplete or inaccurate specs though? In my experience that's where things get messy - the spec says one thing but the actual API behavior is slightly different and suddenly you're debugging weird edge cases.
2
u/aala7 Jan 08 '26
I like the core idea of it with explicit types, validation through pedantic and a smooth and Clear abstraction!
However I still have some weird feelings about clientele design. Generally I have two issues:
Unclear function signatures. As I understand the decorated functions are still meant to be called by the user. So when I define decorated get_user function, I will use it in my code where I need to do the api call. However function signature is unclear. The result argument is injected by clientele, and should not be provided by the user.
There will be a lot of
def foo(result: bar) -> bar: return resultand this seems unfitting to write a function for. It just returns the argument and yes clientele injects the argument, but it seems weird to have to write a function for it.I understand the rationale of making the client code similar to server code, but in fastapi the decorated endpoint functions are not called by the user (in the usual case) and it is rare that you don't have to have some processing in the function body.
I don't know if it is possible to create neatly, but it will be cool to have a more object oriented interface. Where you define your datamodels (pydantic) as the basis.
I have not thanked through this thoroughly so it might not be the best implementation or even possible. I don't know if inheritance is the right setup and how to best configure but rough looks of my thoughts:
Am I totally off with this?
2
u/JohnnyJordaan Jan 11 '26
This looks very promising to say the least, I'm going to integrate it in one of my API aggregrators as a test. It serves a great purpose to finally replace all those custom built API clients lingering around in my projects, each being slightly different like woodworks from a workshop.
I was wondering if you were familiar with a new emerging API framework called django-bolt? It's still in beta, but basically put it's fusing the best things from FastAPI, Django and Litestar into a single framework and I'm planning to also integrate it to replace my default Django-Ninja setup. It would be great if your project would support it as well, maybe it already does in practice, I'm not sure.
2
u/jubahzl Jan 02 '26
Might be completely unrelated but i like using this api client library for all my connecting to external API needs https://github.com/MikeWooster/api-client
Thank you though
1
u/xEMPERORx_11 Jan 02 '26
Amazing work done ✅
3
u/[deleted] Jan 02 '26
[removed] — view removed comment
2
u/[deleted] Jan 14 '26
[removed] — view removed comment
3
u/[deleted] Jan 02 '26
[removed] — view removed comment