File: api.rst

package info (click to toggle)
django-tastypie 0.9.10-2
  • links: PTS
  • area: main
  • in suites: wheezy
  • size: 1,020 kB
  • sloc: python: 6,530; makefile: 78; sh: 45
file content (99 lines) | stat: -rw-r--r-- 2,401 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
.. _ref-api:

===
Api
===

In terms of a REST-style architecture, the "api" is a collection of resources.
In Tastypie, the ``Api`` gathers together the ``Resources`` & provides a nice
way to use them as a set. It handles many of the URLconf details for you,
provides a helpful "top-level" view to show what endpoints are available &
some extra URL resolution juice.


Quick Start
===========

A sample api definition might look something like (usually located in a
URLconf)::

    from tastypie.api import Api
    from myapp.api.resources import UserResource, EntryResource
    
    v1_api = Api(api_name='v1')
    v1_api.register(UserResource())
    v1_api.register(EntryResource())
    
    # Standard bits...
    urlpatterns = patterns('',
        (r'^api/', include(v1_api.urls)),
    )


``Api`` Methods
===============

Implements a registry to tie together the various resources that make up
an API.

Especially useful for navigation, HATEOAS and for providing multiple
versions of your API.

Optionally supplying ``api_name`` allows you to name the API. Generally,
this is done with version numbers (i.e. ``v1``, ``v2``, etc.) but can
be named any string.

``register``
~~~~~~~~~~~~

.. method:: Api.register(self, resource, canonical=True):

Registers an instance of a ``Resource`` subclass with the API.

Optionally accept a ``canonical`` argument, which indicates that the
resource being registered is the canonical variant. Defaults to
``True``.

``unregister``
~~~~~~~~~~~~~~

.. method:: Api.unregister(self, resource_name):

If present, unregisters a resource from the API.

``canonical_resource_for``
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: Api.canonical_resource_for(self, resource_name):

Returns the canonical resource for a given ``resource_name``.

``override_urls``
-----------------

.. method:: Api.override_urls(self):

A hook for adding your own URLs or overriding the default URLs. Useful for
adding custom endpoints or overriding the built-in ones.

Should return a list of individual URLconf lines (**NOT** wrapped in
``patterns``).

``urls``
~~~~~~~~

.. method:: Api.urls(self):

*Property*

Provides URLconf details for the ``Api`` and all registered
``Resources`` beneath it.

``top_level``
~~~~~~~~~~~~~

.. method:: Api.top_level(self, request, api_name=None):

A view that returns a serialized list of all resources registers
to the ``Api``. Useful for discovery.