From 115e61be0900b3d5dd93ff84f20629311aceff9f Mon Sep 17 00:00:00 2001
From: Tom Christie
Date: Tue, 9 Oct 2012 12:01:17 +0100
Subject: Added quickstart guide

---
 docs/index.md                                     |  12 ++
 docs/template.html                                |   1 +
 docs/tutorial/quickstart.md                       | 133 ++++++++++++++++++++++
 rest_framework/decorators.py                      |   3 +-
 rest_framework/templates/rest_framework/base.html |   2 +-
 rest_framework/urlpatterns.py                     |  25 +++-
 6 files changed, 172 insertions(+), 4 deletions(-)
 create mode 100644 docs/tutorial/quickstart.md

diff --git a/docs/index.md b/docs/index.md
index f9795c1a..6a9f7980 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -58,6 +58,7 @@ Note that the base URL can be whatever you want, but you must include `rest_fram
 
 ## Quickstart
 
+Can't wait to get started?  The [quickstart guide][quickstart] is the fastest way to get up and running with REST framework.
 
 ## Tutorial
 
@@ -118,6 +119,12 @@ Run the tests:
 
     ./rest_framework/runtests/runtests.py
 
+## Support
+
+For support please see the [REST framework discussion group][group], or try the  `#restframework` channel on `irc.freenode.net`.
+
+Paid support is also available from [DabApps], and can include work on REST framework core, or support with building your REST framework API.  Please contact [Tom Christie][email] if you'd like to discuss commercial support options.
+
 ## License
 
 Copyright (c) 2011-2012, Tom Christie
@@ -149,6 +156,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [markdown]: http://pypi.python.org/pypi/Markdown/
 [yaml]: http://pypi.python.org/pypi/PyYAML
 
+[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
@@ -183,3 +191,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [migration]: topics/migration.md
 [changelog]: topics/changelog.md
 [credits]: topics/credits.md
+
+[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
+[DabApps]: http://dabapps.com
+[email]: mailto:tom@tomchristie.com
\ No newline at end of file
diff --git a/docs/template.html b/docs/template.html
index 757586dc..d94bef4a 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -37,6 +37,7 @@
               <li class="dropdown">
                 <a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
                 <ul class="dropdown-menu">
+                  <li><a href="{{ base_url }}/tutorial/quickstart{{ suffix }}">Quickstart</a></li>
                   <li><a href="{{ base_url }}/tutorial/1-serialization{{ suffix }}">1 - Serialization</a></li>
                   <li><a href="{{ base_url }}/tutorial/2-requests-and-responses{{ suffix }}">2 - Requests and responses</a></li>
                   <li><a href="{{ base_url }}/tutorial/3-class-based-views{{ suffix }}">3 - Class based views</a></li>
diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md
new file mode 100644
index 00000000..1e9ed725
--- /dev/null
+++ b/docs/tutorial/quickstart.md
@@ -0,0 +1,133 @@
+# Quickstart
+
+We're going to create a simple API to allow admin users to view and edit the users and groups in the system.
+
+Create a new Django project, and start a new app called `quickstart`.  Once you've set up a database and got everything synced and ready to go open up the app's directory and we'll get coding...
+
+## Serializers
+
+First up we're going to define some serializers in `quickstart/serializers.py` that we'll use for our data representations.
+
+    from django.contrib.auth.models import User, Group
+    from rest_framework import serializers
+    
+    
+    class UserSerializer(serializers.HyperlinkedModelSerializer):
+        class Meta:
+            model = User
+            fields = ('url', 'username', 'email', 'groups')
+    
+    
+    class GroupSerializer(serializers.HyperlinkedModelSerializer):
+        class Meta:
+            model = Group
+            fields = ('url', 'name', 'permissions')
+
+Notice that we're using hyperlinked relations in this case, with `HyperlinkedModelSerializer`.  You can also use primary key and various other relationships, but hyperlinking is good RESTful design.
+
+## Views
+
+Right, we'd better right some views then.  Open `quickstart/views.py` and get typing.
+
+    from django.contrib.auth.models import User, Group
+    from rest_framework import generics
+    from rest_framework.decorators import api_view
+    from rest_framework.reverse import reverse
+    from rest_framework.response import Response
+    from quickstart.serializers import UserSerializer, GroupSerializer
+    
+    
+    @api_view(['GET'])
+    def api_root(request, format=None):
+        """
+        The entry endpoint of our API.
+        """
+        return Response({
+            'users': reverse('user-list', request=request),
+            'groups': reverse('group-list', request=request),
+        })
+    
+    
+    class UserList(generics.ListCreateAPIView):
+        """
+        API endpoint that represents a list of users.
+        """
+        model = User
+        serializer_class = UserSerializer
+    
+    
+    class UserDetail(generics.RetrieveUpdateDestroyAPIView):
+        """
+        API endpoint that represents a single user.
+        """
+        model = User
+        serializer_class = UserSerializer
+    
+    
+    class GroupList(generics.ListCreateAPIView):
+        """
+        API endpoint that represents a list of groups.
+        """
+        model = Group
+        serializer_class = GroupSerializer
+    
+    
+    class GroupDetail(generics.RetrieveUpdateDestroyAPIView):
+        """
+        API endpoint that represents a single group.
+        """
+        model = Group
+        serializer_class = GroupSerializer
+
+Let's take a moment to look at what we've done here before we move on.  We have one function-based view representing the root of the API, and four class-based views which map to our database models, and specify which serializers should be used for representing that data.  Pretty simple stuff.
+
+## URLs
+
+Okay, let's wire this baby up.  On to `quickstart/urls.py`...
+
+    from django.conf.urls import patterns, url, include
+    from rest_framework.urlpatterns import format_suffix_patterns
+    from quickstart.views import UserList, UserDetail, GroupList, GroupDetail
+    
+
+    urlpatterns = patterns('quickstart.views',
+        url(r'^$', 'api_root'),
+        url(r'^users/$', UserList.as_view(), name='user-list'),
+        url(r'^users/(?P<pk>\d+)/$', UserDetail.as_view(), name='user-detail'),
+        url(r'^groups/$', GroupList.as_view(), name='group-list'),
+        url(r'^groups/(?P<pk>\d+)/$', GroupDetail.as_view(), name='group-detail'),
+    )
+
+    
+    # Format suffixes
+    urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'api'])
+
+
+    # Default login/logout views
+    urlpatterns += patterns('',
+        url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
+    )
+
+There's a few things worth noting here.
+
+Firstly the names `user-detail` and `group-detail` are important.  We're using the default hyperlinked relationships without explicitly specifying the view names, so we need to use names of the style `{modelname}-detail` to represent the model instance views.
+
+Secondly, we're modifying the urlpatterns using `format_suffix_patterns`, to append optional `.json` style suffixes to our URLs.
+
+Finally, we're including default login and logout views for use with the browsable API.  That's optional, but useful if your API requires authentication and you want to use the browseable API.
+
+## Settings
+
+We'd also like to set a few global settings.  We'd like to turn on pagination, and we want our API to only be accessible to admin users.
+
+    INSTALLED_APPS = (
+        ...
+        'rest_framework',
+    )
+
+    REST_FRAMEWORK = {
+        'PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser'),
+        'PAGINATE_BY': 10
+    }
+
+Okay, that's us done.
diff --git a/rest_framework/decorators.py b/rest_framework/decorators.py
index 2adbff24..948973ae 100644
--- a/rest_framework/decorators.py
+++ b/rest_framework/decorators.py
@@ -13,7 +13,8 @@ def api_view(http_method_names):
         class WrappedAPIView(APIView):
             pass
 
-        WrappedAPIView.http_method_names = [method.lower() for method in http_method_names]
+        allowed_methods = set(http_method_names) | set(('options',))
+        WrappedAPIView.http_method_names = [method.lower() for method in allowed_methods]
 
         def handler(self, *args, **kwargs):
             return func(*args, **kwargs)
diff --git a/rest_framework/templates/rest_framework/base.html b/rest_framework/templates/rest_framework/base.html
index f213554b..abf3672f 100644
--- a/rest_framework/templates/rest_framework/base.html
+++ b/rest_framework/templates/rest_framework/base.html
@@ -39,7 +39,7 @@
                         {% if user.is_authenticated %}
                             <li class="dropdown">
                                 <a href="#" class="dropdown-toggle" data-toggle="dropdown">
-                                    Welcome, {{ user }}
+                                    Logged in as {{ user }}
                                     <b class="caret"></b>
                                 </a>
                                 <ul class="dropdown-menu">
diff --git a/rest_framework/urlpatterns.py b/rest_framework/urlpatterns.py
index a040b621..386c78a2 100644
--- a/rest_framework/urlpatterns.py
+++ b/rest_framework/urlpatterns.py
@@ -2,13 +2,34 @@ from django.conf.urls.defaults import url
 from rest_framework.settings import api_settings
 
 
-def format_suffix_patterns(urlpatterns, suffix_required=False, suffix_kwarg=None):
+def format_suffix_patterns(urlpatterns, suffix_required=False,
+                           suffix_kwarg=None, allowed=None):
     """
     Supplement existing urlpatterns with corrosponding patterns that also
     include a '.format' suffix.  Retains urlpattern ordering.
+
+    suffix_required:
+        If `True`, only suffixed URLs will be generated, and non-suffixed
+        URLs will not be used.  Defaults to `False`.
+
+    suffix_kwarg:
+        The name of the kwarg that will be passed to the view.
+        Defaults to 'format'.
+
+    allowed:
+        An optional tuple/list of allowed suffixes.  eg ['json', 'api']
+        Defaults to `None`, which allows any suffix.
+
     """
     suffix_kwarg = suffix_kwarg or api_settings.FORMAT_SUFFIX_KWARG
-    suffix_pattern = r'\.(?P<%s>[a-z]+)$' % suffix_kwarg
+    if allowed:
+        if len(allowed) == 1:
+            allowed_pattern = allowed[0]
+        else:
+            allowed_pattern = '(%s)' % '|'.join(allowed)
+        suffix_pattern = r'\.(?P<%s>%s)$' % (suffix_kwarg, allowed_pattern)
+    else:
+        suffix_pattern = r'\.(?P<%s>[a-z]+)$' % suffix_kwarg
 
     ret = []
     for urlpattern in urlpatterns:
-- 
cgit v1.2.3