Tuning your API
===============

Sometimes the defaults ``piston_mini_client`` provides won't be what you need,
or you just need to customize the requests you send out for one part or
another of your API.  In those cases, ``piston_mini_client`` will strive to
stay out of your way.

================
Handling Failure
================

A common issue is what to do if the webservice returns an error.  One possible
solution (and the default for ``piston-mini-client``) is to raise an
exception.

This might not be the best solution for everybody, so piston-mini-client
allows you to customize the way in which such failures are handled.

You can do this by defining a ``FailHandler`` class.  This class needs to
provide a single method (``handle``), that receives the response headers and
body, and decides what to do with it all.  It can raise an exception, or
modify the body in any way.

If it returns a string this will be assumed to be the (possibly
fixed) body of the response and will be deserialized by any decorators the
method has.

To use a different fail handler in your ``PistonAPI`` set the ``fail_handler``
class attribute.  For example, to use the
``NoneFailHandler`` instead of the default ``ExceptionFailHandler``,
you can use::

    class MyAPI(PistonAPI):
        fail_handler = NoneFailHandler
        # ... rest of the client definition...

``piston-mini-client`` provides four fail handlers out of the box:

 * ``ExceptionFailHandler``: The default fail handler, raises ``APIError`` if
   anything goes wrong
 * ``NoneFailHandler``: Returns None if anything goes wrong.  This will
   provide no information about *what* went wrong, so only use it if you don't
   really care.
 * ``DictFailHandler``: If anything goes wrong it returns a dict with all the
   request and response headers and body, requested url and method, for you
   to debug.
 * ``MultiExceptionFailHandler``: Raises a different exception according to
   what went wrong.

===============================
Talking to dual http/https apis
===============================

Often your API provides a set of public calls, and some other calls that
are authenticated.

Public calls sometimes are heavily used, so we'd like to
serve them over http.  They're public anyway.

Authenticated calls involve some sensitive information passing with the user's
credentials, so we like serving those over https.

Once you've got all this set up on the server, you can ask piston_mini_client
to make each call using the appropriate scheme by using the ``scheme``
optional argument when you call ``_get``, ``_post``, ``_put`` or ``_delete``::

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

        def public_method(self):
            return self._get('public_method/', scheme='http')

        def private_method(self):
            return self._post('private_method/', scheme='https')

        def either(self):
            return self._get('either/')

In this case, no matter what scheme the service root uses, calls to
``public_method()`` will result in
an http request, and calls to ``private_method()``  will result in an https
request.  Calls to ``either()`` will leave the scheme alone, so it will
follow the scheme used to instantiate the api, or fall back to
``default_service_root``'s scheme.

===========================
Customizing request headers
===========================

If you need to send custom headers to the server in your requests you can
specify these both in the ``PistonAPI`` instance as an instance or class
variable, or when you make calls to ``_get``, ``_post``, ``_put`` or
``_delete``.
Specifying headers as a class variable will add the same custom headers
to all requests made by all instances of the class::

    class MyAPI(PistonAPI):
        extra_headers = {'X-Requested-With': 'XMLHttpRequest'}
        # ... etc

Here these ``extra_headers`` will be added to any and all requests made by
``MyAPI`` instances.  You could also specify an extra header for a single
instance of ``MyAPI``::

    api = MyAPI()
    api.extra_headers = {'X-Somethingelse': 'dont forget to buy milk'}

In this case you'll get this extra header in all requests made by this
instance of ``MyAPI``.

Finally, you can also pass in an optional ``extra_headers`` argument into
each call to ``_get``, ``_post``, ``_put`` or ``_delete``, if only specific api
calls need to be provided additional headers::

    class MyAPI(PistonAPI):
        def crumble(self):
            return self._get('crumble')
        def icecream(self):
            return self._get('icecream',
                extra_headers={'X-secret-sauce': 'chocolate'})

Here calls to ``icecream`` will use the extra special header, but other calls
(like ``crumble``) won't.


================================================
Customizing the serializer for each content type
================================================

``piston_mini_client`` provides a set of default serializers, but sometimes
you have your own serialization convention, set by the server, and the client
just needs to comply.  In that case, you can implement your own serializer and
add *an instance* of it to the ``serializers`` class attribute.

To define a serializer all you need to provide is a ``serialize`` method,
that should take a single ``obj`` argument and return it serialized into
a string::

    class ReprSerializer(object):
        def serialize(self, obj):
            return repr(obj)

    class MyAPI(PistonAPI):
        serializers = {'application/json': ReprSerializer()}

In this case, any POST/PUT request that goes out with a content type of
``application/json`` will use your ``ReprSerializer`` for serializing its
data into the request body.

If you need to serialize only arguments of a certain specific API call with
this special serializer, you can serialize data before
calling ``_post``/``_put``::

    class GroceryAPI(PistonAPI):
        def order(self, shopping_list):
            serializer = ReprSerializer()
            self._post('somecall', data=serializer.serialize(shopping_list))

Passing a string into the ``data`` argument skips serialization altogether,
so you can apply whichever serialization you want before calling ``_post`` or
``_put``, and ``piston_mini_client`` will avoid double-serializing your
request body.

=================
Logging to a file
=================

If you need to debug the actual requests and responses on the wire, you can
initialize a ``PistonAPI`` passing in a ``log_filename`` argument.
``piston_mini_client`` will append all requests and responses, including
headers, status code and all, to this file.

Also, if you're debugging an application that uses ``piston_mini_client``
but don't want to (or can't) start hacking at the code, you can set
``PISTON_MINI_CLIENT_LOG_FILENAME`` in the environment to point a file,
and all ``PistonAPI`` instances will use this location by default. That is,
unless they're explicitly being instantiated to log elsewhere.

=================
Handling timeouts
=================
When you instantiate a ``PistonAPI`` you can provide an optional ``timeout``
argument that will be used as a socket timeout for the requests that instance
makes.  To explicitly set no timeout, pass in ``timeout=0``.  If you leave
the default ``timeout=None``, the instance will first check for an environment
variable ``PISTON_MINI_CLIENT_DEFAULT_TIMEOUT``, and if that is undefined or
invalid, then the class's default timeout will be used; this can be defined
by setting a ``default_timeout`` class attribute when
writing the API class.  Finally, if the class's default timeout is
also ``None``, Python's system-wide socket default timeout will be used.

You can't currently define timeouts on a per-request basis.  If you need to
change the timeout used for certain requests, you'll need to use a new
``PistonAPI`` instance.