ApiBee
======
ApiBee is a dynamic rest client built on top of the excellent restkit_ library.
.. _restkit : http://github.com/benoitc/restkit
It aims to be able to handle any uris for any apis.
How it work ?
-------------
Let's say we want to fetch the json API of the great service http://www.example.com. Their api is served from http://api.example.com/1.0/::
>>> from apibee import Client
>>> api = Client('http://api.example.com/1.0/')
Now we want to get the result from http://api.example.com/1.0/users/search?q=Timy::
>>> results = api.users.search(q='Timy')
That's it !
Going further
-------------
Getting json result
+++++++++++++++++++
Here::
class ExampleClient(Client):
def process_result(self, result):
return json.loads(result)
Now the result is a python type::
>>> api = ExampleClient("http://api.example.com/1.0/")
>>> result = api.user.search(q="timy")
Adding query automatically
++++++++++++++++++++++++++
Sometimes some api are a bit tricky. And we need to build a custom client to match thoses.
Previously, the version of the api was part of the resource but what if we have to specify it for each request::
http://api.example.com/user/search?v=1.0&q=Timy
We can specify one or more params which will be automatically add to the query::
class ExampleClient(Client):
def set_persistent_query(**args):
self._persistent_query = args
def build_query(self, response, query):
query.update(self._persistent_query)
return response, query
>>> api = ExampleClient('http://api.example.com')
>>> api.set_persistent_query(v="1.0")
Customize resources
+++++++++++++++++++
Some apis like Twitter add `.json` after the resource but before the query : https://api.twitter.com/1/search.json&q=Timy. We can do it like this::
class TwitterClient(Client):
def set_format(self, f):
self._format = f
def build_query(self, response, query):
response = "%s.%s" % (response, self._format)
return response, query
>>> api = TwitterClient('https://api.twitter.com/1', end_resource='.json')
>>> results = api.search(q='Timy')
Raising errors
++++++++++++++
Sometimes you may have to clean up the result before send it back. You can do it by overloading the `Client.process_result` method.
Example:
Google's web service won't send an http error 400 if the request failed. Instead, it will send a custom result::
http://ajax.googleapis.com/ajax/services/search/web?q=Earth%20Day
will send back::
{"responseData": null, "responseDetails": "invalid version", "responseStatus": 400}
Let's say we want to catch the error and raise an RequestFailed exception with a custom message which is in the "responseDetails" field::
class GoogleClient(Client):
def process_result(self, result):
if result["responseStatus"] == 400:
raise RequestFailed(result['responseDetails'])
return result
That's it ! Don't forget to return the result at the end of the `process_result` method.
>>> api = GoogleClient('http://ajax.googleapis.com/ajax/services')
>>> api.search.web(q="toto")
Traceback (most recent call last):
...
RequestFailed: invalid version
