Skip to main content

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

Project description

Build Status


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


RestORM structures the way you access a RESTful API and allows you to easily access related resources. It tries to be as generic as possible so it’s not tailored to any specific API or server-side API library. With RestORM you can mock an entire API and replace the real client with a mock version in unit tests. RestORM is very extensible but offers many functionalities out of the box to get you up and running quickly.

Currently, RestORM works on Python 2.5+ with Python 3 support on its way.


  • Object relational mapping of API resources (Django-like but does not depend on Django at all).

  • Flexible client architecture that can be used with your own or third party clients (like oauth).

  • Extensive mocking module allows you to mock API responses, or even complete API’s.

  • Examples for Twitter and Flickr API.

Quick start

This is a compressed version of the tutorial. The full documentation can be found here.

Create a client

A typical client that can talk to a RESTful API using JSON, is no more then:

from restorm.clients.jsonclient import JSONClient

client = JSONClient(root_uri='')

Instead of this client, we mock its intended behaviour.

Create a mock API

In order to test your client, you can emulate a whole API using the MockApiClient and add pre-defined responses.

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

from restorm.clients.mockclient import MockApiClient

mock_client = MockApiClient(
        'book/': {'GET': ({'Status': 200}, [{'isbn': 1, 'title': 'Dive into Python', 'resource_url': ''}])},
        'book/1': {'GET': ({'Status': 200}, {'isbn': 1, 'title': 'Dive into Python', 'author': ''})},
        'author/': {'GET': ({'Status': 200}, [{'id': 1, 'name': 'Mark Pilgrim', 'resource_url': ''}])},
        'author/1': {'GET': ({'Status': 200}, {'id': 1, 'name': 'Mark Pilgrim'})}

Define resources

We start with our main resource, the Book resource as a subclass of Resource. Two attributes in the inner Meta class indicate a URL-pattern how we can access all books (list) and a single book (item):

from restorm.resource import Resource

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

Bringing it all together

You can access the Book resource and the (runtime created) related Author resource using the mock_client:

>>> book = Book.objects.get(isbn=1, client=mock_client) # Get book with ISBN number 1.
>>>['title'] # 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'


RestORM is on PyPI, so you can simply use:

$ pip install restorm

If you want the latest development version, get the code from Github:

$ pip install -e git+git://



December 4, 2012

  • Fixed bug in MockClient to pop the correct response.

  • Added restorm.conf.settings to store the DEFAULT_CLIENT to use.

  • Added ability to create a development server from your MockApiClient.

  • Added root_uri parameter to Client constructor.

  • Added initial XML client implemention (alpha).

  • Added initial documentation.

  • Added simplejson 2.2.1 or above as required library.


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.2.tar.gz (28.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page