Skip to main content

RestORM allows you to interact with resources as if they were objects.

Project description


RestORM allows you to interact with resources as if they were objects (object relational mapping), mock entire webservices and incorporate custom client logic.


Most RESTful webservices are very easy to access with very little code. RestORM is just a small layer on top of httplib2.Http to get a response from a webservice. However, instead of regular Python dict objects, you’ll get a dict-like object that knows how to access related resources as well.

Until a version 1.0 release, backwards incompatible changes may be introduced in future 0.x versions.


  • Object relational mapping of webservice resources.
  • Flexible client architecture that can be used with your own or third party clients (like oauth).
  • Extensive mocking module allows you to mock webservice responses, or even complete webservices.

Getting started

Create a mock webservice

In order to test your client, you can emulate a whole webservice using the MockApiClient. However, sometimes it’s faster or easier to use a single, predefined response, using the MockClient and MockResponse (sub)classes.

You can also use FileResponse class to return the contents of a file as response in combination with the MockApiClient.

The mock webservice below contains a list of books and a list of authors. To keep it simple, both lists contain only 1 item

from restorm.clients.mockclient import MockApiClient

client = MockApiClient(
        '/api/book/': {
            'GET': ({'Status': 200}, [{'id': 1, 'name': 'Dive into Python', 'resource_url': ''}]),
            'POST': ({'Status': 201, 'Location': ''}, ''),
        '/api/book/1': {'GET': ({'Status': 200}, {'id': 1, 'name': 'Dive into Python', 'author': ''})},
        '/api/author/': {'GET': ({'Status': 200}, [{'id': 1, 'name': 'Mark Pilgrim', 'resource_url': ''}])},
        '/api/author/1': {'GET': ({'Status': 200}, {'id': 1, 'name': 'Mark Pilgrim'})}

Define resources

Setup your client side resource definitions:

from restorm.resource import Resource

class Book(Resource):
    class Meta:
        list = (r'^book/$', 'book_set')
        item = r'^book/(?P<id>\d)$'
        root = ''

Make it work

You can simply access the Book resource:

>>> book = Book.objects.get(id=1, client=client) # Get book with ID 1.
>>>['name'] # Get the value of the key "name".
u'Dive Into Python'
>>>['author'] # Get the value of the key "author".
>>> author = # Perform a GET on the "author" resource.
u'Mark Pilgrim'


As you may have noticed, the response content contains actual Python objects. The MockApiClient simply returns the content as is. If you prefer using JSON, you can achieve the same behaviour with:

from restorm.clients.mockclient import BaseMockApiClient
from restorm.clients.jsonclient import JSONClientMixin

class JSONMockApiClient(BaseMockApiClient, JSONClientMixin):

client = JSONMockApiClient(
        # Note the difference. The content is now JSON.
        'book/1': {'GET': ({'Status': 200, 'Content-Type': 'application/json'}, '{"id": 1, "name": "Dive into Python", "author": ""}',
        # ...


  1. Get the code from Github:

    $ git clone git://
  2. Create and activate a virtual environment:

    $ cd restclient
    $ virtualenv .
    $ source bin/activate
  3. Setup the project for development:

    $ python develop
  4. Start hacking!


RestORM has a whooping 90% test coverage. Although reaching 100% is not a goal by itself, I consider unit testing to be essential during development.

Performing the unit tests yourself:

python test



November 9, 2012

  • Initial version released on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

restorm-0.1.tar.gz (23.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page