Metadata-Version: 1.1
Name: mvoauthapi
Version: 0.2
Summary: Mobile Vikings OAuth API Client
Home-page: http://github.com/kvsn/mvoauthapi
Author: Koen Vossen
Author-email: koen.vossen@citylive.be
License: BSD
Description: ===============================
        Mobile Vikings OAuth API Client
        ===============================
        
        .. contents::
        
        
        Overview
        ========
        
        OAuth is an authorization protocol that allows applications (a balance checker
        on your Android phone, for example) to consume user data from a service
        provider (the Mobile Vikings API) data without having to know the user's
        credentials. The ``mvoauthapi`` package contains a client for the Mobile
        Vikings API with OAuth support.
        
        
        Installation
        ============
        
        Run the following command in the directory containing this ``README`` file::
        
            python setup.py install
        
        
        Calling the Mobile Vikings API
        ==============================
        
        The ``call.py`` file contains a sample implementation that calls the Mobile
        Vikings API using the OAuth client. To request the balance on a SIM card,
        for example, execute the following command::
        
            python call.py sim_balance add_price_plan=1
        
        You will be prompted for a consumer key and secret. These credentials can be
        found on your Mobile Vikings `account settings page`_.
        
        .. _`account settings page`: https://mobilevikings.com/account/settings/
        
        Visit the `API documentation`_ page for an overview of the available methods
        and their arguments.
        
        .. _`API documentation`: http://mobilevikings.com/api/2.0/doc/
        
        If the `xAuth extension`_ has been enabled for your consumer, you can test it by
        passing the ``-x`` option to ``call.py``. You will be prompted for an account's
        username and password instead of being redirected to the Mobile Vikings site.
        Note that xAuth is not enabled by default. If you're developing a mobile app
        and want to use it, email us at mailto:info@mobilevikings.com.
        
        .. _`xAuth extension`: https://dev.twitter.com/docs/oauth/xauth
        
        ``call.py`` will store your consumer credentials and tokens in
        ``~/.mvoauthapi.cfg`` so you don't have to re-enter your data and go through
        the access token request process each time you make a call.
        
        
        Using the client in your application
        ====================================
        
        Acquiring an access token
        -------------------------
        
        The OAuth protocol implements authorization by exchanging tokens. First, the
        application fetches a request token with a given callback URL. Using this
        token, it can redirect the user to an authorization URL on the Mobile Vikings
        site. On this page, the user is asked if she wants to grant permission to the
        application. If she does, she is redirected to the callback URL that now
        contains a verification code. The application can then use the verification
        code to request an access token. With this access token, the API calls can
        finally be made.
        
        ::
        
            from mvoauthapi.client import ApiClient, Token
            api = ApiClient(consumer_key, consumer_secret)
            api.fetch_request_token(callback='http://my-app.com/access_granted')
            url = api.make_authorization_url()
        
        Now, redirect the user to the authorization URL. If she accepts, she will be
        redirected to the ``access_granted`` page of your site. There will be
        ``oauth_verifier`` and ``oauth_token`` GET query parameters present in the URL.
        Pass them to the client and fetch the access token.
        
        ::
        
            request_key = request.GET['oauth_token']
            request_secret = '' # Fetch this from your session or db.
            verifier = request.GET['oauth_verifier']
            request_token = Token(request_key, request_secret)
            request_token.set_verifier(verifier)
            api = ApiClient(consumer_key, consumer_secret)
            api.set_request_token(request_token)
            access_token = api.fetch_access_token()
        
        You can now use the ``api`` object to make calls.
        
        ::
        
            api.get('top_up_history')
        
        Note: if you don't want to use a redirect to your application's site, omit the
        ``callback`` argument in the ``fetch_request_token`` call. The Mobile Vikings
        API will then display the verification code to the user when access has been
        granted.
        
        Using the xAuth extension
        -------------------------
        
        Simply call ``fetch_access_token_via_xauth()`` after initializing the
        client. It is imperative that you do *not* store the user's credentials. Use
        them once to request the access token and discard them afterwards. From then
        on, use the access token to make calls.
        
        ::
        
            api = ApiClient(consumer_key, consumer_secret)
            api.fetch_access_token_via_xauth(username, password)
            api.get('sim_balance')
        
        
        Re-using an existing access token
        ---------------------------------
        
        Your application can re-use the access token once it has been acquired; you
        need not go through the authorization process again. The token will stay valid
        until the user revokes it.
        
        ::
        
            api = ApiClient(consumer_key, consumer_secret)
            api.set_access_token(access_token)
            api.get('sim_balance')
        
        
        Support
        =======
        
        If you have questions, comments or suggestions, pay a visit to the `Mobile
        Vikings API users group`_.
        
        .. _`Mobile Vikings API users group`: http://groups.google.com/group/mobile-vikings-api-users
        
        
        .. vim: tw=79
        
Keywords: mobile vikings oauth api client
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
