skip to navigation
skip to content

apiclient 1.0.2

Framework for making good API client libraries using urllib3.

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()

{'what': 'world'}
>>>'/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 ='/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(


  • Tests.
  • More documentation.
  • More types of API handshakes, like OAuth and OAuth2.
  • More examples.


Any contribution is highly encouraged and desired. :)

  1. Fork on Github.
  2. Make the changes. Bonus points if changes include documentation and tests.
  3. 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.




1.0.2 (2011-10-20)

  • Fixed from failing upon not seeing README.rst when installing using easy_install.

1.0.1 (2011-10-10)

  • Fixed package not including a

1.0 (2011-10-03)

  • Published decoupled code from SocialGrapple.
File Type Py Version Uploaded on Size
apiclient-1.0.2.tar.gz (md5) Source 2011-10-21 4KB
  • Downloads (All Versions):
  • 162 downloads in the last day
  • 825 downloads in the last week
  • 3252 downloads in the last month