{"id":22508530,"url":"https://github.com/bianchidotdev/python-api-client-boilerplate","last_synced_at":"2025-08-03T13:30:52.052Z","repository":{"id":50196062,"uuid":"176633731","full_name":"bianchidotdev/Python-API-Client-Boilerplate","owner":"bianchidotdev","description":"Dead simple boilerplate for a Python API Client","archived":false,"fork":false,"pushed_at":"2022-12-08T01:42:27.000Z","size":437,"stargazers_count":6,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2023-06-10T22:23:14.756Z","etag":null,"topics":["api","api-client","api-wrapper","python","requests-module"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bianchidotdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-20T02:09:51.000Z","updated_at":"2023-06-10T22:23:14.756Z","dependencies_parsed_at":"2023-01-25T02:15:09.700Z","dependency_job_id":null,"html_url":"https://github.com/bianchidotdev/Python-API-Client-Boilerplate","commit_stats":null,"previous_names":["bianchidotdev/python-api-client-boilerplate"],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bianchidotdev%2FPython-API-Client-Boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bianchidotdev%2FPython-API-Client-Boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bianchidotdev%2FPython-API-Client-Boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bianchidotdev%2FPython-API-Client-Boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bianchidotdev","download_url":"https://codeload.github.com/bianchidotdev/Python-API-Client-Boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228545874,"owners_count":17934814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","api-wrapper","python","requests-module"],"created_at":"2024-12-07T01:21:16.653Z","updated_at":"2024-12-07T01:21:17.156Z","avatar_url":"https://github.com/bianchidotdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Client Boilerplate\n\nThis project's aim is to facilitate the consumption of APIs that do not have a provided Python SDK (or a poorly written Python SDK). \n\nMany services out ther provide great SDKs with much more tailored features than could be provided generally. However, there are others that either provide just an API endpoint, with no SDKs, or only a small subset of SDKs, limited to the languages they are using internally. \n\nAfter stumbling across several of these services, and after failing to find a clear and simple example or generator for Python API wrappers, I decided to publish this, which is a simple bare-bones API client that implements extensive logging for debugging and other best practices I've found along the way.\n\nNotable mention to [Tapioca](https://github.com/vintasoftware/tapioca-wrapper), which is a better place to start if you want a much more fully fledged API client, but which provides less visibility and customizability into the core.\n\n\n## Code Flow\n\nEverything starts with the Client class. The Client class will handle establishing the session that will be used across all successive requests as well as the authentication used.\n\nOne of the main design decisions here was to pass every single request through an internal `_make_request` function on the Client, which also handles logging the request and response, handling response status codes, and parsing the response.\n\nFrom the get-go, you will always be able to use the public `make_request` function which requires you to specify the endpoint, and optionally, the method, query params, or a body.\n\nHowever, the real value from having an API client comes from implementing all the other functions to pass in native Python objects (like a list of tags or a datetime object) and have it converted to the correct format accepted by the API (like a comma-delimited string, or seconds since the epoch). Since this is so specific to the API, this will need to be done manually, but the `make_request` function will give you the foundation for communications until you implement API-specific functions.\n\nBy default, all responses will parsed as JSON, and will default to text if not valid JSON.\n\n## System Requirements\n- [git](https://git-scm.com/)\n- [Python3](https://docs.python-guide.org/starting/installation/)\n- [pip](https://pip.pypa.io/en/stable/installing/) - most likely already installed as part of Python\n\nAll of these must be available in your `PATH`. To verify things are set up properly, you can run this:\n\n```sh\ngit --version\npython3 --version # it's possible your python3 binary is python\npip3 --version # it's also possible your pip3 binary is pip\n```\n\nIf you have trouble with any of these, learn more about the PATH environment variables and how to fix it here for [windows](https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/) or [mac/linux](http://stackoverflow.com/a/24322978/971592).\n\n## Setup\n\nFirst, clone the repo:\n\n```sh\ngit clone \u003cthis repo\u003e\ncd \u003crepo name\u003e\n```\n\nPython is a little divided on how to manage environments. If you know what you're doing, feel free to use whatever you prefer (`pipenv`, `venv`, global `pip`, etc.).\n\nOtherwise, run these commands:\n\n```sh\nvirtualenv venv\nsource venv/bin/activate #or venv/bin/activate.fish\npip3 install -r requirements.txt\n```\n\n## How to use it\n\nThis is just a boilerplate client. At the very minimum, here are the steps required for creating a functional Python client:\n- In exampleClient.py, change the URL near the top to match the API you are calling\n- Set environment variables in whatever context will be running your code for authentication (Basic auth is most common). This could be VS Code, any other IDE, a terminal emulator, or on a hosting provider's site.\n\nExample shell:\n```sh\nexport AUTH_TYPE='HTTPBASICAUTH'\nexport CLIENT_USER='user@example.com'\nexport CLIENT_PASSWORD='4r3L1ygO0dp45$w0rd!12345'\n```\n\nExample VSCode:\n\n![VSCode Env Var](images/vscodeEnvVar.png)\n\n### Simple Test\n\nFor a trivial test just to validate the client is working as expected, you can just add in a test case in the `if __name__ == \"__main__\":` section at the bottom. \n\nAny code included here will run ONLY if the `exampleClient.py` file is run directly.\n\nIt can also be helpful to set the environment variable `DEBUG=1` to get debugging output from the HTTP requests.\n\n```py\nif __name == \"__main__\":\n  client = Example()\n  users = client.make_request('/api/v1/users')\n  logger.info(users)\n```\n\n\n### Using the client as a module\n\nMost of the time, you'll have a program that is using this client for just calling the API and you'll have other logic held somewhere else.\n\nAssuming this `exampleClient.py` file is in the same directory as your consuming code, you can use the following:\n\n```py\nimport Example from exampleClient\n\nclient = Example() # instantiates a client object - uses environment variables for auth if present\nresources = client.make_request('/api/v1/resources') # will send a GET request to the resources endpoint\nusers = client.get_users() # \n\njohn = client.get_user(id=\"12\") # returns the user object for John\n```\n\n## Roadmap\n\nThings I'd like to include:\n- Make Python2/3 compatible\n- Generate a client from the boilerplate given an OpenAPI url\n- HTTP_Method class in place of Strings\n- Handle responses other than JSON more elegantly\n- Handle rate limiting\n- Handle retries on `5XX` status codes\n- Implement a better non-environment-variable based configuration management system\n- Create a `setup.py`\n\n## Common Issues\n\n\nIf you are not using a virtual environment of any sort, the default shebang command (`/usr/bin/env python`) might default to `python2`. \n\nYou can change this to the absolute path of your `python` binary or update it to explicitly call out `/usr/bin/env python3`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbianchidotdev%2Fpython-api-client-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbianchidotdev%2Fpython-api-client-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbianchidotdev%2Fpython-api-client-boilerplate/lists"}