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/tutorial/quickstart.md | 133 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/tutorial/quickstart.md (limited to 'docs/tutorial/quickstart.md') 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\d+)/$', UserDetail.as_view(), name='user-detail'), + url(r'^groups/$', GroupList.as_view(), name='group-list'), + url(r'^groups/(?P\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. -- cgit v1.2.3 From e9475d036ff2fa0244ca0f947192ffa842391784 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 12:03:29 +0100 Subject: Tweak settings in quickstart guide --- docs/tutorial/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorial/quickstart.md') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 1e9ed725..62338160 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -126,7 +126,7 @@ We'd also like to set a few global settings. We'd like to turn on pagination, a ) REST_FRAMEWORK = { - 'PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser'), + 'DEFAULT_PERMISSIONS': ('rest_framework.permissions.IsAdminUser',), 'PAGINATE_BY': 10 } -- cgit v1.2.3 From 94401b43d2a1be81304ddcd91e3a97e7d2a42c4c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 13:50:26 +0100 Subject: Flesh out quickstart guide and make some style tweaks --- docs/tutorial/quickstart.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs/tutorial/quickstart.md') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 62338160..cf5933ad 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -131,3 +131,42 @@ We'd also like to set a few global settings. We'd like to turn on pagination, a } Okay, that's us done. + +--- + +## Testing our API + +We can now access our API, both from the command-line, using tools like `curl`... + + bash: curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "email": "admin@example.com", + "groups": [], + "url": "http://127.0.0.1:8000/users/1/", + "username": "admin" + }, + { + "email": "tom@example.com", + "groups": [], + "url": "http://127.0.0.1:8000/users/2/", + "username": "tom" + } + ] + } + +Or directly through the browser... + +![Quick start image][image] + +Great, that was easy! + +If you want to get a more in depth understanding of how REST framework fits together head on over to [the tutorial][tutorial], or start browsing the [API guide][guide]. + +[image]: ../images/quickstart.png +[tutorial]: 1-serialization.md +[guide]: ../#api-guide \ No newline at end of file -- cgit v1.2.3 From ce21fa1dc6dd8c941b71d9219360b3e9083051d4 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 14:12:38 +0100 Subject: Tweak static files with docs --- docs/tutorial/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorial/quickstart.md') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index cf5933ad..85411378 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -167,6 +167,6 @@ Great, that was easy! If you want to get a more in depth understanding of how REST framework fits together head on over to [the tutorial][tutorial], or start browsing the [API guide][guide]. -[image]: ../images/quickstart.png +[image]: ../img/quickstart.png [tutorial]: 1-serialization.md [guide]: ../#api-guide \ No newline at end of file -- cgit v1.2.3 From 7367bd53a908474f14f0f44f3744f2fcb1f4111c Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Fri, 12 Oct 2012 10:02:21 +0200 Subject: Fix tiny typo --- docs/tutorial/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorial/quickstart.md') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 85411378..851db3c7 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -27,7 +27,7 @@ Notice that we're using hyperlinked relations in this case, with `HyperlinkedMod ## Views -Right, we'd better right some views then. Open `quickstart/views.py` and get typing. +Right, we'd better write some views then. Open `quickstart/views.py` and get typing. from django.contrib.auth.models import User, Group from rest_framework import generics -- cgit v1.2.3 From fed235dd0135c3eb98bb218a51f01ace5ddd3782 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Oct 2012 23:09:11 +0100 Subject: Make settings consistent with corrosponding view attributes --- docs/tutorial/quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorial/quickstart.md') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 851db3c7..6bde725b 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -126,7 +126,7 @@ We'd also like to set a few global settings. We'd like to turn on pagination, a ) REST_FRAMEWORK = { - 'DEFAULT_PERMISSIONS': ('rest_framework.permissions.IsAdminUser',), + 'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',), 'PAGINATE_BY': 10 } @@ -169,4 +169,4 @@ If you want to get a more in depth understanding of how REST framework fits toge [image]: ../img/quickstart.png [tutorial]: 1-serialization.md -[guide]: ../#api-guide \ No newline at end of file +[guide]: ../#api-guide -- cgit v1.2.3