added docs for CapakeyRestGateway refs #45

docs/usage.rst

@@ -98,3 +98,38 @@ See the examples folder for some more sample code.
 
 .. _agiv: http://www.agiv.be
 .. _dogpile: https://bitbucket.org/zzzeek/dogpile.cache
+
+
+Using the CAPAKEY REST gateway
+-------------------------
+
+To make life easier and capakey more pythonic, we've also implemented a rest gateway
+that abstracts some more of the service and provides richer objects as responses.
+
+.. literalinclude:: /../examples/capakey_restgateway.py
+   :language: python
+
+The CAPAKEY REST gateway supports caching through the dogpile_ caching library. Caching can
+be added by passing a configuration dictionary to the :class:`CapakeyRestGateway`.
+
+Three caching regions will be configured:
+
+- `permanent`: For requests that can be cached for a very long time,
+  eg. `list_gemeenten`.
+- `long`: For requests that can be cached for a fairly long time, 
+  eg. `list_secties_by_afdeling`.
+- `short`: For requests that will only be cached for a little while, 
+  eg. `get_perceel_by_capakey`.
+
+Please bear in mind that in this case short can probably be fairly long. We 
+suspect that the database underlying the capakey service is not updated that
+regularly, so a short caching duration could easily be one hour or even a day.
+
+.. literalinclude:: /../examples/capakey_gateway_caching.py
+   :language: python
+
+
+See the examples folder for some more sample code.
+
+.. _agiv: http://www.agiv.be
+.. _dogpile: https://bitbucket.org/zzzeek/dogpile.cache