david / django-roa (http://welldev.org/)

Turn your models into remote resources that you can access through Django's ORM. ROA stands for Resource Oriented Architecture.

Clone this repository (size: 560.7 KB): HTTPS / SSH
$ hg clone http://code.welldev.org/django-roa

Developing with Django-ROA

Specifications

Client side

Model

Available methods and limitations:

  • save(): Creates or updates the object
  • delete(): Deletes the object, do not delete in cascade

Manager

Available methods and limitations:

  • all(): Returns all the elements of a QuerySet
  • get_or_create(): Get or create an object
  • delete(): Deletes the records in the current QuerySet
  • filter(): Returns a filtered QuerySet, do not handle Q objects
  • exclude(): Returns a filtered QuerySet, do not handle Q objects
  • order_by(): Returns an ordered QuerySet
  • count(): Returns the number of elements of a QuerySet
  • latest(): Returns the latest element of a QuerySet
  • [start:end]: Returns a sliced QuerySet, useful for pagination

Fields

Available fields:

  • Auto # Custom AutoField doesn't work yet but default id one works
  • Boolean
  • Char
  • Date
  • DateTime
  • Decimal
  • Email
  • FilePath
  • Float
  • Integer
  • NullBoolean
  • Slug
  • Text
  • Time
  • URL

Relations

Available relations:

  • ForeignKey
  • ManyToMany # Intermediary model required using the through argument

Admin

Available options: all except search_fields because of advanced querysets (Q() objects).

Server side

URLs

Required URLs and limitations:

  • /{resource}/: used for retrieving lists (GET) or creating objects (POST)
  • /{resource}/{id}/: used for retrieving an object (GET), updating it (PUT) or deleting (DELETE) it
  • /{resource}/count/: used for retrieving the number of objects (GET) for the given resource

Notes: URL id is required but you can choose a totally different URL scheme given the get_resource_url_* methods, a complete example is available in tests' projects. /count/ is not hardcoded, you can choose another pattern per resource.

Parameters

Optional parameters:

  • filter_* and exclude_*: * is the string used by Django to filter/exclude
  • order_by: order the results given this field
  • limit_start and limit_stop: slice the results given those integers
  • format: json, xml, django or your own format

Note: Take a look at the ROA_ARGS_NAMES_MAPPING setting below to customize parameters' names.

Settings

List of custom settings:

  • ROA_MODELS: A boolean, turn to True if you'd like to access distant resources, useful to switch from a local development to a production remote server in a breath.
  • ROA_FORMAT: A string, turn to "xml" if you prefer this serialization format over the default one (json). Note that json serialization doesn't work with BooleanFields set to None because of #5563 Django's bug.
  • ROA_HEADERS: A dictionary, specify the headers sent by restkit to the server (Content-Type and so on).
  • ROA_DJANGO_ERRORS: A boolean, turn to True if you use the MethodDispatcher class from django_roa_server, it will display more readable errors.
  • ROA_URL_OVERRIDES_*: A dictionary mapping "app_label.model_name" strings to functions that take a model object and return its URL. This is a way of overriding get_resource_url_* methods on a per-installation basis. Note that the model name used in this setting should be all lower-case, regardless of the case of the actual model class name. Same behavior as ABSOLUTE_URL_OVERRIDES setting, see examples.
  • ROA_MODEL_NAME_MAPPING: A list of tuples which determines local application name -> remote application name replacement, useful for django's format serialization.
  • ROA_ARGS_NAMES_MAPPING: A dictionary mapping of parameters' names passed to the server to filter data, useful if the server has its own parameters' names (see examples). Existing names are: FORMAT, ORDER_BY, LIMIT_START, LIMIT_STOP, FILTER_, EXCLUDE_. You can also use the complete name to map a totally different one: filter__pk to id for instance (see twitter_roa example).
  • ROA_CUSTOM_ARGS: A dictionary of arguments passed to each requested URL, useful if the server is waiting for additional parameters (depth, incoming format and so on).

Commands

  • inspectresources: Introspect models and returns a representation of resources, useful if you need to pass specifications to the resource provider.

Still TODO

  • Handle remote ContentTypes in admin, very hard without rewriting it
  • Handle cache (ETags & co)
  • Improve links between models
  • Handle image/file fields (design decision needed)
  • Deal with authentications

This revision is from 2010-01-07 00:20