Emitters are what spews out the data, and are the things responsible for speaking YAML, JSON, XML, Pickle and Django. They currently reside in emitters.py as XMLEmitter, JSONEmitter, YAMLEmitter, PickleEmitter and DjangoEmitter.
Writing your own emitters is easy, all you have to do is create a class that subclasses Emitter and has a render method. The render method will receive 1 argument, ‘request’, which is a copy of the request object, which is useful if you need to look at request.GET (like defining callbacks, like the JSON emitter does.)
To get the data to serialize/render, you can call self.construct() which always returns a dictionary. From there, you can do whatever you want with the data and return it (as a unicode string.)
Note
New in 23ebc37c78e8 : Emitters can now be registered with the Emitter.register function, and can be removed (in case you want to remove a built-in emitter) via the Emitter.unregister function.
The built-in emitters are registered like so:
class JSONEmitter(Emitter):
...
Emitter.register('json', JSONEmitter, 'application/json; charset=utf-8')
If you write your own emitters, you can import Emitter and call ‘register’ on it to put your emitter into action. You can also overwrite built-in, or existing emitters, by using the same name (the first argument.)
This makes it very easy to add support for extended formats, like protocol buffers or CSV.
Emitters are accessed via the ?format GET argument, e.g. ‘/api/blogposts/?format=yaml’, but since 23ebc37c78e8 , it is now possible to access them via a special keyword argument in your URL mapping. This keyword is called ‘emitter_format’ (to not clash with your own ‘format’ keyword), and can be used like so:
urlpatterns = patterns('',
url(r'^blogposts(?P<emitter_format>.+)$', ...),
)
Now a request for /blogposts.json will use the JSON emitter, etc.
Additionally, you may specify the format in your URL mapping, via the keyword arguments shortcut:
urlpatterns = patterns('',
url(r'^blogposts$', resource_here, { 'emitter_format': 'json' }),
)