Docs, docs, docs

This commit is contained in:
Tom Christie 2013-04-25 20:43:37 +01:00
parent 7268a5c571
commit 74b3307978
7 changed files with 66 additions and 11 deletions

View File

@ -34,7 +34,7 @@ The example above would generate the following URL patterns:
### Extra link and actions
Any `@link` or `@action` methods on the viewsets will also be routed.
Any methods on the viewset decorated with `@link` or `@action` will also be routed.
For example, a given method like this on the `UserViewSet` class:
@action(permission_classes=[IsAdminOrIsSelf])
@ -45,8 +45,6 @@ The following URL pattern would additionally be generated:
* URL pattern: `^users/{pk}/set_password/$` Name: `'user-set-password'`
# API Guide
## SimpleRouter
@ -82,7 +80,43 @@ This router is similar to `SimpleRouter` as above, but additionally includes a d
<tr><td>POST</td><td>@action decorated method</td></tr>
</table>
## AutoRouter
The AutoRouter class is similar to the `DefaultRouter` class, except that it doesn't require you to register any viewsets, but instead automatically creates routes for all installed models.
It can be useful for prototyping, although for anything more advanced you'll want to drop down to using one of the other router classes, and registering viewsets explicitly.
The following code shows how you can automatically include a complete API for your application with just a few lines of code, using the `AutoRouter` class:
from django.conf.urls import patterns, url, include
from rest_framework.routers import AutoRouter
urlpatterns = patterns('',
url(r'^api/', include(AutoRouter().urls)),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
)
# Custom Routers
Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specfic requirements about how the your URLs for your API are strutured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset.
## Example
The following example will only route to the `list` and `retrieve` actions, and unlike the routers included by REST framework, it does not use the trailing slash convention.
class ReadOnlyRouter(SimpleRouter):
"""
A router for read-only APIs, which doesn't use trailing suffixes.
"""
routes = [
(r'^{prefix}$', {'get': 'list'}, '{basename}-list'),
(r'^{prefix}/{lookup}$', {'get': 'retrieve'}, '{basename}-detail')
]
## Advanced custom routers
If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls()` method. The method should insect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute.
[cite]: http://guides.rubyonrails.org/routing.html

View File

@ -114,6 +114,8 @@ The `@action` and `@link` decorators can additionally take extra arguments that
def set_password(self, request, pk=None):
...
---
# API Reference
## ViewSet

View File

@ -288,3 +288,13 @@ footer a:hover {
@media (max-width: 650px) {
.repo-link.btn-inverse {display: none;}
}
td, th {
padding: 0.25em;
background-color: #f7f7f9;
border-color: #e1e1e8;
}
table {
border-color: white;
}

View File

@ -173,6 +173,7 @@ General guides to using REST framework.
* [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas]
* [2.0 Announcement][rest-framework-2-announcement]
* [2.2 Announcement][2.2-announcement]
* [2.3 Announcement][2.3-announcement]
* [Release Notes][release-notes]
* [Credits][credits]
@ -280,6 +281,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[contributing]: topics/contributing.md
[rest-framework-2-announcement]: topics/rest-framework-2-announcement.md
[2.2-announcement]: topics/2.2-announcement.md
[2.3-announcement]: topics/2.3-announcement.md
[release-notes]: topics/release-notes.md
[credits]: topics/credits.md

View File

@ -101,6 +101,7 @@
<li><a href="{{ base_url }}/topics/rest-hypermedia-hateoas{{ suffix }}">REST, Hypermedia & HATEOAS</a></li>
<li><a href="{{ base_url }}/topics/rest-framework-2-announcement{{ suffix }}">2.0 Announcement</a></li>
<li><a href="{{ base_url }}/topics/2.2-announcement{{ suffix }}">2.2 Announcement</a></li>
<li><a href="{{ base_url }}/topics/2.3-announcement{{ suffix }}">2.3 Announcement</a></li>
<li><a href="{{ base_url }}/topics/release-notes{{ suffix }}">Release Notes</a></li>
<li><a href="{{ base_url }}/topics/credits{{ suffix }}">Credits</a></li>
</ul>

View File

@ -4,7 +4,7 @@ REST framework 2.3 is geared towards making it easier and quicker to build your
## ViewSets & Routers
We've introduced
**TODO**
## Easier Serializers
@ -43,17 +43,17 @@ Similarly, you can now easily include the primary key in hyperlinked relationshi
model = Blog
fields = ('url', 'id', 'title', 'created', 'comments')
## Less complex views
## Simpler views
This release rationalises the API and implementation of the Generic views, dropping the dependancy on Django's `SingleObjectMixin` and `MultipleObjectMixin` classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.
This release rationalises the API and implementation of the generic views, dropping the dependancy on Django's `SingleObjectMixin` and `MultipleObjectMixin` classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.
This improvement is reflected in improved documentation for the `GenericAPIView` base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses.
---
## API Changes
# API Changes
### Simplified generic view classes
## Simplified generic view classes
The functionality provided by `SingleObjectAPIView` and `MultipleObjectAPIView` base classes has now been moved into the base class `GenericAPIView`. The implementation of this base class is simple enough that providing subclasses for the base classes of detail and list views is somewhat unnecessary.
@ -118,9 +118,11 @@ And would have the following entry in the urlconf:
Usage of the old-style attributes continues to be supported, but will raise a `PendingDeprecationWarning`.
## Other notes
---
### Explict view attributes
# Other notes
## Explict view attributes
The usage of `model` attribute in generic Views is still supported, but it's usage is being discouraged in favour of using explict `queryset` and `serializer_class` attributes.
@ -147,7 +149,10 @@ It also makes it the usage of overridden `get_queryset()` or `get_serializer_cla
"""
return self.user.accounts
### Django 1.3 support
## Django 1.3 support
The 2.3 release series will be the last series to provide compatiblity with Django 1.3.
## What comes next?
The plan for the next few months is to concentrate on addressing outstanding tickets. 2.4 is likely to deal with relatively small refinements to the existing API.

View File

@ -77,6 +77,7 @@ path_list = [
'topics/contributing.md',
'topics/rest-framework-2-announcement.md',
'topics/2.2-announcement.md',
'topics/2.3-announcement.md',
'topics/release-notes.md',
'topics/credits.md',
]