diff options
Diffstat (limited to 'docs/index.md')
| -rw-r--r-- | docs/index.md | 57 |
1 files changed, 36 insertions, 21 deletions
diff --git a/docs/index.md b/docs/index.md index f66ba7f4..497f1900 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,12 +5,24 @@ **A toolkit for building well-connected, self-describing Web APIs.** -**WARNING: This documentation is for the 2.0 redesign of REST framework. It is a work in progress.** +--- + +**Note**: This documentation is for the 2.0 version of REST framework. If you are looking for earlier versions please see the [0.4.x branch][0.4] on GitHub. + +--- Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. +If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcement][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. + +There is also a sandbox API you can use for testing purposes, [available here][sandbox]. + +**Below**: *Screenshot from the browseable API* + +![Screenshot][image] + ## Requirements REST framework requires the following: @@ -20,18 +32,18 @@ REST framework requires the following: The following packages are optional: -* [Markdown][markdown] (2.1.0+) - Markdown support for the self describing API. +* [Markdown][markdown] (2.1.0+) - Markdown support for the browseable API. * [PyYAML][yaml] (3.10+) - YAML content-type support. +* [django-filter][django-filter] (0.5.4+) - Filtering support. ## Installation -**WARNING: These instructions will only become valid once this becomes the master version** - Install using `pip`, including any optional packages you want... pip install djangorestframework - pip install markdown # Recommended if using the browseable API. - pip install pyyaml # Required for yaml content-type support. + pip install markdown # Markdown support for the browseable API. + pip install pyyaml # YAML content-type support. + pip install django-filter # Filtering support ...or clone the project from github. @@ -40,21 +52,21 @@ Install using `pip`, including any optional packages you want... pip install -r requirements.txt pip install -r optionals.txt -Add `rest_framework` to your `INSTALLED_APPS`. +Add `'rest_framework'` to your `INSTALLED_APPS` setting. INSTALLED_APPS = ( ... 'rest_framework', ) -If you're intending to use the browseable API you'll want to add REST framework's login and logout views. Add the following to your root `urls.py` file. +If you're intending to use the browseable API you'll probably also want to add REST framework's login and logout views. Add the following to your root `urls.py` file. urlpatterns = patterns('', ... url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) ) -Note that the URL path can be whatever you want, but you must include `rest_framework.urls` with the `rest_framework` namespace. +Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. ## Quickstart @@ -67,9 +79,8 @@ The tutorial will walk you through the building blocks that make up REST framewo * [1 - Serialization][tut-1] * [2 - Requests & Responses][tut-2] * [3 - Class based views][tut-3] -* [4 - Authentication, permissions & throttling][tut-4] +* [4 - Authentication & permissions][tut-4] * [5 - Relationships & hyperlinked APIs][tut-5] -<!-- * [6 - Resource orientated projects][tut-6]--> ## API Guide @@ -83,9 +94,11 @@ The API guide is your complete reference manual to all the functionality provide * [Renderers][renderers] * [Serializers][serializers] * [Serializer fields][fields] +* [Serializer relations][relations] * [Authentication][authentication] * [Permissions][permissions] * [Throttling][throttling] +* [Filtering][filtering] * [Pagination][pagination] * [Content negotiation][contentnegotiation] * [Format suffixes][formatsuffixes] @@ -98,12 +111,10 @@ The API guide is your complete reference manual to all the functionality provide General guides to using REST framework. -* [CSRF][csrf] * [Browser enhancements][browser-enhancements] * [The Browsable API][browsableapi] * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] -* [Contributing to REST framework][contributing] -* [2.0 Migration Guide][migration] +* [2.0 Announcement][rest-framework-2-announcement] * [Release Notes][release-notes] * [Credits][credits] @@ -119,7 +130,6 @@ Run the tests: ./rest_framework/runtests/runtests.py -For more information see the [Contributing to REST framework][contributing] section. ## Support For support please see the [REST framework discussion group][group], or try the `#restframework` channel on `irc.freenode.net`. @@ -128,7 +138,7 @@ Paid support is also available from [DabApps], and can include work on REST fram ## License -Copyright (c) 2011-2012, Tom Christie +Copyright (c) 2011-2013, Tom Christie All rights reserved. Redistribution and use in source and binary forms, with or without @@ -151,19 +161,22 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -[travis]: http://travis-ci.org/tomchristie/django-rest-framework?branch=restframework2 -[travis-build-image]: https://secure.travis-ci.org/tomchristie/django-rest-framework.png?branch=restframework2 +[travis]: http://travis-ci.org/tomchristie/django-rest-framework?branch=master +[travis-build-image]: https://secure.travis-ci.org/tomchristie/django-rest-framework.png?branch=master [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ [yaml]: http://pypi.python.org/pypi/PyYAML +[django-filter]: http://pypi.python.org/pypi/django-filter +[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X +[image]: img/quickstart.png +[sandbox]: http://restframework.herokuapp.com/ [quickstart]: tutorial/quickstart.md [tut-1]: tutorial/1-serialization.md [tut-2]: tutorial/2-requests-and-responses.md [tut-3]: tutorial/3-class-based-views.md -[tut-4]: tutorial/4-authentication-permissions-and-throttling.md +[tut-4]: tutorial/4-authentication-and-permissions.md [tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md -[tut-6]: tutorial/6-resource-orientated-projects.md [request]: api-guide/requests.md [response]: api-guide/responses.md @@ -173,9 +186,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [renderers]: api-guide/renderers.md [serializers]: api-guide/serializers.md [fields]: api-guide/fields.md +[relations]: api-guide/relations.md [authentication]: api-guide/authentication.md [permissions]: api-guide/permissions.md [throttling]: api-guide/throttling.md +[filtering]: api-guide/filtering.md [pagination]: api-guide/pagination.md [contentnegotiation]: api-guide/content-negotiation.md [formatsuffixes]: api-guide/format-suffixes.md @@ -189,7 +204,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [browsableapi]: topics/browsable-api.md [rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md [contributing]: topics/contributing.md -[migration]: topics/migration.md +[rest-framework-2-announcement]: topics/rest-framework-2-announcement.md [release-notes]: topics/release-notes.md [credits]: topics/credits.md |