Merge pull request #1784 from tomchristie/remove-model-attribute

Deprecate `.model` attribute on views

1 files changed, 55 insertions, 19 deletions

diff --git a/README.md b/README.md
index 7052ab63..d3317739 100644
--- a/README.md
+++ b/README.md
@@ -39,40 +39,51 @@ Add `'rest_framework'` to your `INSTALLED_APPS` setting.
 
     INSTALLED_APPS = (
         ...
-        'rest_framework',        
+        'rest_framework',
     )
 
 # Example
 
 Let's take a look at a quick example of using REST framework to build a simple model-backed API for accessing users and groups.
 
-Here's our project's root `urls.py` module:
+Startup up a new project like so... 
+
+    pip install django
+    pip install djangorestframework
+    django-admin startproject example .
+    ./manage.py syncdb
+
+Now edit the `example/urls.py` module in your project:
 
 ```python
-from django.conf.urls.defaults import url, patterns, include
-from django.contrib.auth.models import User, Group
-from rest_framework import viewsets, routers
+from django.conf.urls import url, include
+from django.contrib.auth.models import User
+from rest_framework import serializers, viewsets, routers
+
+# Serializers define the API representation.
+class UserSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = User
+        fields = ('url', 'username', 'email', 'is_staff')
+
 
 # ViewSets define the view behavior.
 class UserViewSet(viewsets.ModelViewSet):
-    model = User
-
-class GroupViewSet(viewsets.ModelViewSet):
-    model = Group
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
 
     
-# Routers provide an easy way of automatically determining the URL conf
+# Routers provide a way of automatically determining the URL conf.
 router = routers.DefaultRouter()
 router.register(r'users', UserViewSet)
-router.register(r'groups', GroupViewSet)
 
 
 # Wire up our API using automatic URL routing.
 # Additionally, we include login URLs for the browseable API.
-urlpatterns = patterns('',
+urlpatterns = [
     url(r'^', include(router.urls)),
     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-)
+]
 ```
 
 We'd also like to configure a couple of settings for our API.
@@ -80,12 +91,12 @@ We'd also like to configure a couple of settings for our API.
 Add the following to your `settings.py` module:
 
 ```python
-REST_FRAMEWORK = {
-    # Use hyperlinked styles by default.
-    # Only used if the `serializer_class` attribute is not set on a view.
-    'DEFAULT_MODEL_SERIALIZER_CLASS':
-        'rest_framework.serializers.HyperlinkedModelSerializer',
+INSTALLED_APPS = (
+    ...  # Make sure to include the default installed apps here.
+    'rest_framework',        
+)
 
+REST_FRAMEWORK = {
     # Use Django's standard `django.contrib.auth` permissions,
     # or allow read-only access for unauthenticated users.
     'DEFAULT_PERMISSION_CLASSES': [
@@ -93,10 +104,35 @@ REST_FRAMEWORK = {
     ]
 }
 ```
-Don't forget to make sure you've also added `rest_framework` to your `INSTALLED_APPS` setting.
 
 That's it, we're done!
 
+    ./manage.py runserver
+
+You can now open the API in your browser at `http://127.0.0.1:8000/`, and view your new 'users' API. If you use the `Login` control in the top right corner you'll also be able to add, create and delete users from the system.
+
+You can also interact with the API using command line tools such as [`curl`](http://curl.haxx.se/). For example, to list the users endpoint:
+
+    $ curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/
+	[
+	    {
+	        "url": "http://127.0.0.1:8000/users/1/", 
+	        "username": "admin", 
+	        "email": "admin@example.com", 
+	        "is_staff": true, 
+	    }
+	]
+
+Or to create a new user:
+
+    $ curl -X POST -d username=new -d email=new@example.com -d is_staff=false -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/
+    {
+        "url": "http://127.0.0.1:8000/users/2/", 
+        "username": "new", 
+        "email": "new@example.com", 
+        "is_staff": false, 
+    }
+
 # Documentation & Support
 
 Full documentation for the project is available at [http://www.django-rest-framework.org][docs].