Registry / http-networking / apiclient

apiclient

JSON →
library1.0.4pypypi✓ verified 85d ago

apiclient is a simple, lightweight Python framework for building API clients for REST-like services, leveraging `urllib3` for HTTP requests. It provides decorators for defining API endpoints and handles the boilerplate of request building and response processing. The current version is 1.0.4, with recent minor updates indicating active maintenance.

pip install apiclient
INSTALL
IMPORT
SIG · APICLIENT
A
apiclient
http-networkingpythonv1.0.4
Install
2.7s avg
Import
236ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.241s · 20.4MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.7s · import 0.230s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

APIClient
from apiclient import APIClient
endpoint
from apiclient import endpoint

This example demonstrates how to define a simple GitHub API client using `APIClient` and the `endpoint` decorator. It fetches public repositories for a given user, explicitly handles the response object for status checking and JSON parsing, and includes basic error handling for network and HTTP errors.

import os from apiclient import APIClient, endpoint import urllib3.exceptions # Import for specific error handling class GitHubClient(APIClient): @endpoint def get_user_repos(self, username: str): # The 'get' method returns a apiclient._response.ResponseWrapper object return self.get(f'/users/{username}/repos') # Initialize the client. For authentication, pass headers. # Use os.environ.get for an example of token usage. token = os.environ.get('GITHUB_TOKEN', '') headers = {'Authorization': f'token {token}'} if token else {} client = GitHubClient(base_url='https://api.github.com', headers=headers) try: # Call the endpoint. The wrapped urllib3 response is returned. response = client.get_user_repos(username='shazow') # apiclient returns wrapped urllib3 responses directly. # Always check status and explicitly parse JSON. response.raise_for_status() # Raises an exception for HTTP error codes (e.g., 404, 500) repos = response.json() # Parses the JSON body print(f"Successfully fetched {len(repos)} repositories for shazow.") if repos: print(f"First repository: {repos[0]['name']}") except urllib3.exceptions.HTTPError as e: print(f"HTTP Error: {e.status} - {e.reason}") except urllib3.exceptions.MaxRetryError as e: print(f"Network Error: Could not connect to host. {e}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaExplicit Response Handling Required: `apiclient`'s `@endpoint` methods return a wrapped `urllib3` response object (type `apiclient._response.ResponseWrapper`). While this wrapper provides convenient `.json()` and `.raise_for_status()` methods, users must explicitly call them to parse the body or check for HTTP errors. The library does not automatically perform these actions.
fix
After calling an `endpoint` method, always follow up with `response.raise_for_status()` to check for errors and `response.json()` (or `response.text`, `response.content`) to access the response body.
affects: All versions
gotchaMinimal Feature Set - Implement Advanced Logic Manually: `apiclient` is a lightweight framework for defining API clients. It does not include built-in features like automatic retries with exponential backoff, rate limit handling, advanced caching, or request signing beyond basic headers. These must be implemented by the user if required for robust production clients.
fix
Extend the `APIClient` or specific endpoint methods with custom logic to handle retries, rate limits, or other advanced scenarios using `urllib3` directly or other helper libraries.
affects: All versions
gotchaPotential for Indirect Impact from `urllib3` Updates: `apiclient` relies on `urllib3` for its HTTP core. While `apiclient` maintains its own stability, breaking changes, deprecations, or security updates in `urllib3` can indirectly affect your client's behavior or require updates to your environment. `apiclient` requires `urllib3>=1.26.0`.
fix
Keep `urllib3` updated to a version compatible with `apiclient` (and address any `urllib3` specific warnings). Monitor `urllib3` release notes for changes relevant to HTTP client behavior.
affects: All versions dependent on `urllib3`
Errors
Common errors & fixes
urllib3.exceptions.MaxRetryError: HTTPConnectionPool(...)` or `urllib3.exceptions.NewConnectionError: <urllib3.connection.HTTPConnection object at ...>: Failed to establish a new connection: [Errno ...]
These exceptions indicate network connectivity issues, an incorrect `base_url` (e.g., wrong host, port, or protocol), or the API server being unreachable.
fix
Verify network connection, check `base_url` for typos, ensure the target API server is online and accessible. Consider adding retry logic to your client.
urllib3.exceptions.HTTPError: HTTP 401: Unauthorized` (or `403: Forbidden`, `404: Not Found`, etc.)
The API server returned an error status code. This could be due to invalid or missing authentication credentials, incorrect endpoint path, or a resource not being found.
fix
Ensure your authentication headers are correctly set (e.g., `Authorization` header), verify the API key/token is valid, and double-check the `endpoint` path and method (e.g., `get` vs. `post`). Remember to call `response.raise_for_status()` to explicitly raise these HTTP errors.
Upgrade
Version history
1.0.4latest on PyPI · released Mar 21, 2019
Audit
Dependencies
urllib3requiredCore HTTP client library used by apiclient.
Agent activity
20 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources
apiclient — pip install apiclient · libregistry