Getting Started
===============

All you really need to do is inherit from PistonAPI and define the methods
your api provides.  Each method can specify what arguments it takes, what
authentication method should be used, and how to process the response.

=================
One simple method
=================

Say your server's urls.py defines a single pattern for the web API like::

    urlpatterns = patterns('',
        url(r'^myapicall$', myapicall_resource),
    )


Then all you'll need to define your client code is something like::

    from piston_mini_client import PistonAPI, returns_json

    class MyAPI(PistonAPI):
        default_service_root = 'http://myhostname.com/api/1.0'

        @returns_json
        def myapicall(self):
            return self._get('myapicall')

And that's it.  Some things worth noticing here:
 * Your api client class should provide a default service root, that will be
   used if instantiated with no service root.  When instantiating ``MyAPI``
   your users will be able to override this.
 * The default service root should usually include any path needed to reach
   your API urls.py.  For example, in this case you can imagine the project's
   ``urls.py`` has a line like::

    urlpatterns = patterns('',
        (r'^api/1.0/', include('myproject.api.urls')),
    )

 * ``@returns_json`` tells ``piston_mini_client`` that the data returned by
   the server will be encoded with json, and so it will be decoded accordingly
   into Python data structures.

 * PistonAPI provides ``_get``, ``_post``, ``_put`` and ``_delete`` methods to
   take care of making the lower level http calls via ``httplib2``.


======================================
Validating arguments to your API calls
======================================

If your server's ``urls.py`` specifies placeholders for resource arguments, as
in::

    urlpatterns = patterns('',
        url(r'^foo/(?P<language>[^/]+)/(?P<foobar_id>\d+)/frobble$',
            myapicall_resource),
    )

You can validate arguments on the client side to avoid unnecessary server
roundtrips with::

    from piston_mini_client import PistonAPI
    from piston_mini_client.validators import validate_pattern

    class MyAPI(PistonAPI):
        default_service_root = 'http://myhostname.com/api/1.0'

        @validate_pattern('foobar_id', r'\d+')
        @validate_pattern('language', r'[^/]+', required=False)
        def myapicall(self, foobar_id, language=None):
            if language is None:
                language = 'en'
            return self._get('foo/%s/%s/frobble' % (language, foobar_id))

The ``validate_pattern`` decorator checks that the necessary keyword argument
is provided and that it matches the pattern that the server is then going to
match against.

If you specify ``required=False`` the argument can be omitted, in which case
the client code should take care of providing a sane default value.

You could also have used the ``validate`` validator in this case that just
checks that a keyword argument is of a certain type::

    from piston_mini_client import PistonAPI
    from piston_mini_client.validators import validate, validate_pattern

    class MyAPI(PistonAPI):
        default_service_root = 'http://myhostname.com/api/1.0'

        @validate('foobar_id', int)
        @validate_pattern('language', r'[^/]+', required=False)
        def myapicall(self, foobar_id, language=None):
            if language is None:
                language = 'en'
            return self._get('foo/%s/%s/frobble' % (language, foobar_id))

Then again, if we use this we'd need to then ensure that ``foobar_id >= 0``.

==============================================
Getting back light-weight objects from the API
==============================================

If your api handlers return JSON, your api handlers can easily specify that
the response should be parsed into small objects that resemble your
server-side models.

For example if your ``handlers.py`` on the server contains::

    class FooBarHandler(BaseHandler):
        model = FooBar
        fields = (
            'name',
            'length',
        )
        allowed_methods = ('GET',)

        def read(self, request, foobar_id):
            try:
                return FooBar.objects.get(pk=foobar_id)
            except FooBar.DoesNotExist:
                return rc.NOT_FOUND

Then, assuming the right url matches this handler in your ``urls.py``, your
Piston client code could use something like::

    from piston_mini_client import PistonResponse, returns

    class FooBarResponse(PistonResponse):
        def __str__(self):
            return '<FooBar: %s>' % self.name

    
    class MyAPI(PistonAPI):
        default_service_root = 'http://myhostname.com/api/1.0'

        @validate('foobar_id', int)
        @returns(FooBarResponse)
        def get_foobar(self, foobar_id):
            return self._get('foobar/%s/' % foobar_id)

...and calls to ``api.get_foobar()`` will return a ``FooBarResponse``, that
will have the right ``name`` and ``length`` attributes.

Note that we could have just skipped the definition of ``FooBarResponse``
and specified ``@returns(PistonResponse)`` but it might be nice to be able to
print one of these responses and get a meaningful output, or we might want
to attach some other method to ``FooBarResponse``.

===========================================
Passing light-weight objects into API calls
===========================================
Same as receiving light-weight objects as responses, ``piston_mini_client``
defines a way to pass in light-weight objects to your API calls, and
have them serialized accordingly.

When calling ``_post`` or ``_put`` you need to pass in a ``data`` argument,
that will be serialized into the body of the request.  This can tipically be
a string (in which case no serialization is performed) or a simple Python data
structure (list, dict, tuple, etc...), but
you can also pass in any object with a ``as_serializable`` method.

``PistonSerializable`` is one such class, that allows you to easily define
a set of attributes that will be serialized into a request's body::

    class AccountRequest(PistonSerializable):
        _atts = ('username', 'password', 'fullname')

    class RegistrationAPI(PistonAPI):
        @validate('account', AccountRequest)
        def register(self, account):
            self._post('register', data=account)

After defining this light-weight ``AccountRequest`` class you can set it up
when you instantiate it or by assigning attributes::

    account = AccountRequest(username='joeb', password='easy123')
    account.fullname = 'Joe Blogs'

    api.register(account)

``PistonSerializable`` will take care of checking that all the needed
attributes have been set when it's serialized, and complain otherwise.  All
attributes will be packed into a dictionary for serializing.  If you have
special serialization needs you can redefine the ``as_serializable`` method,
or use your own light-weight object entirely.  All you need to provide is an
``as_serializable`` method to ensure it works with ``piston_mini_client``'s
serialization mechanism.