skip to navigation
skip to content

wac 0.23

Writing RESTful API clients.

To write a friendly client for a RESTful API you typically end up doing the following:

  • Write HTTP client commands for communicating with the server. These commands do things like marshal payloads, convert errors, invoke request hooks, etc.
  • Turn responses deserialized by your client into resource objects (i.e. objectify the response).
  • Build up queries (e.g. filter, sort) to access resources matching some criteria in perhaps a particular order.

In the ideal case the client gives your users something approximating an ORM for your resources. This library is intended to assist you in writing such a client provided the API you are consuming complies with some basic conventions:

  • Uses HTTP properly.
  • Annotates resource representations with type and URI information.



$ pip install wac

or if you prefer:

$ easy_install wac



Lets work through an example. The code for this example is in

  • First you import wac:
import wac
  • Next define the version of your client:
__version__ = '1.0'
  • Also define the configuration which all Clients will use by default:
default_config = wac.Config(None)
  • Now be nice and define a function for updating the configuration(s):
def configure(root_url, **kwargs):
    default = kwargs.pop('default', True)
    kwargs['client_agent'] = 'example-client/' + __version__
    if 'headers' not in kwargs:
        kwargs['headers'] = {}
    kwargs['headers']['Accept-Type'] = 'application/json'
    if default:
        default_config.reset(root_url, **kwargs)
        Client.config = wac.Config(root_url, **kwargs
  • Now the big one, define your Client which is what will be used to talk to a server:
class Client(wac.Client):

    config = default_config

    def _serialize(self, data):
        data = json.dumps(data, default=self._default_serialize)
        return 'application/json', data

    def _deserialize(self, response):
        if response.headers['Content-Type'] != 'application/json':
            raise Exception(
                "Unsupported content-type '{}'"
        data = json.loads(response.content)
        return data
  • Then define your base Resource:
class Resource(wac.Resource):

    client = Client()
    registry = wac.ResourceRegistry()
  • And finally your actual resources:
class Playlist(Resource):

    type = 'playlist'

    uri_gen = wac.URIGen('/v1/playlists', '{playlist}')

class Song(Resource):

    type = 'song'

    uri_gen = wac.URIGen('/v1/songs', '{song}')
  • Done! Now you can do crazy stuff like this:
import example

example.configure('', auth=('user', 'passwd'))

q = (example.Playlist.query()
for playlist in q:
    song = playlist.songs.create(
        tags=['nuti', 'fluti'])
    song.length += 101


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Write your code and tests
  4. Ensure all tests still pass (python test)
  5. Commit your changes (git commit -am ‘Add some feature’)
  6. Push to the branch (git push origin my-new-feature)
  7. Create new pull request


0.21 (2013-06-18)

  • Require requests >= 1.2.3.

0.19 (2013-05-16)

  • Allow requests version <= 1.1.0.

0.14 (2013-01-29)

  • Pin requests version to less than 1.0 until we test it with requests > 1.0.

0.12 (2012-10-02)

  • Fix ResourceCollection.filter.
  • Add like and ilike filters.
  • Minor pep8/formatting changes.

0.11 (2012-09-11)

  • Fix config copy.

0.10 (2012-07-27)

  • Python 2.6 compatibility.

0.9 (2012-07-25)

  • Save serialization fix.

0.8 (2012-07-25)

  • Pagination fixes.

0.7 (2012-07-20)

  • Misc fixes.

0.3 (2012-05-28)

  • Hope you like it.

0.2 (2012-05-01)

  • Growing pains.

0.1 (2012-04-01)

  • Its alive!
File Type Py Version Uploaded on Size
wac-0.23.tar.gz (md5) Source 2014-04-24 14KB