Permalink
Browse files

Adding documentation and TODO.

  • Loading branch information...
1 parent 99e443f commit 5c9ea21117918da69afb65931df1a0369303d452 @wolever wolever committed Oct 4, 2011
Showing with 43 additions and 18 deletions.
  1. +42 −18 README.rst
  2. +1 −0 apiclient/base.py
View
@@ -16,35 +16,59 @@ Highlights
Examples
========
-How to make your own super-simple client API library: ::
+How to make your own super-simple client API library::
- from apiclient import APIClient
+ >>> 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'}
+ >>>
- class AcmePublicAPI(APIClient):
- BASE_URL = 'https://localhost:1234/'
+How to add rate limiting to your client API library so that we don't exceed 10
+requests per minute::
- acme_api = AcmePublicAPI()
- r = acme_api.call('/stream') # <- Returns parsed JSON response
+ >>> 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/ <https://github.com/shazow/apiclient/blob/master/examples/>`_ directory.
-How to add rate limiting to your client API library so that we don't exceed 10
-requests per minute: ::
- from apiclient import RateLimiter
+Extending
+=========
- lock = RateLimiter(max_messages=10, every_seconds=60)
+To handle different calling conventions, ``apiclient`` can be extended through
+subclassing.
- acme_api = AcmePublicAPI(rate_limit_lock=lock)
+For example, if an API requires that all arguments be JSON encoded, the
+``_compose_url`` method could be implemented like this::
- # 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))
+ >>> 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)
-For more specific API examples, see the
-`examples/ <https://github.com/shazow/apiclient/blob/master/examples/>`_ directory.
+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)
TODO
View
@@ -40,6 +40,7 @@ def __init__(self, api_key, *args, **kw):
self.api_key = api_key
def _compose_url(self, path, params=None):
+ # TODO: fix this, as per our conversation at Oct. 4, 2011, 05:10 UTC
p = {self.API_KEY_PARAM: self.api_key}
if params:

0 comments on commit 5c9ea21

Please sign in to comment.