Metadata-Version: 1.0
Name: apibee
Version: 0.2
Summary: A dynamic api client
Home-page: http://github.com/namlook/apibee
Author: Namlook
Author-email: UNKNOWN
License: New BSD License
Description: 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
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
