Tiny framework for building good API client libraries thanks to urllib3.
- Threadsafely reuses connections with Keep-Alive (via urllib3).
- Small and easy to understand codebase perfect for extending and building upon.
- Built-in support for rate limiting and request throttling.
- Functional examples for the Klout API and the Facebook OpenGraph API.
How to make your own super-simple client API library:
>>> from apiclient import APIClient
>>> class AcmePublicAPI(APIClient):
... BASE_URL = 'https://localhost:1234/'
>>> acme_api = AcmePublicAPI()
>>> acme_api.call('/hello')
{'what': 'world'}
>>> acme_api.call('/echo', params={"ping": "pong"})
{'ping': 'pong'}
How to add rate limiting to your client API library so that we don't exceed 10 requests per minute:
>>> from apiclient import RateLimiter
>>> lock = RateLimiter(max_messages=10, every_seconds=60)
>>> acme_api = AcmePublicAPI(rate_limit_lock=lock)
>>> # Get the first 100 pages
>>> for page in xrange(100):
... # Whenever our request rate exceeds the specifications of the API's
... # RateLimiter, the next request will block until the next request window
... r = acme_api.call('/stream', page=str(page))
For more specific API examples, see the examples/ directory.
To handle different calling conventions, apiclient
can be extended through subclassing.
For example, if an API requires that all arguments be JSON encoded, the _compose_url
method could be implemented like this:
>>> class JSONArgsAPIClient(APIClient):
... def _compose_url(self, path, params=None):
... if params is not None:
... params = dict((key, json.dumps(val))
... for (key, val) in params.iteritems())
... return APIClient._compose_url(self, path, params=params)
Or if an API returns YAML instead of JSON, the _handle_response
method could be overridden:
>>> class YAMLResponseAPIClient(APIClient):
... def _handle_response(self, response):
... return yaml.load(response.data)
- Tests.
- More documentation.
- More types of API handshakes, like OAuth and OAuth2.
- More examples.
Any contribution is highly encouraged and desired. :)
- Fork on Github.
- Make the changes. Bonus points if changes include documentation and tests.
- Send a pull request.
If you're unsure if it's a good idea, open an Issue or contact me to discuss your proposal. Extra juicy bonus points if you pick off some of the items in the TODO list.