diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 11bd76d72..335b69fa5 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -1,6 +1,7 @@ # Quickstart -We're going to create a simple API to allow admin users to view and edit the users and groups in the system. +We're going to create a simple API to allow admin users to view and edit the +users and groups in the system. ## Requirements @@ -53,17 +54,21 @@ Now sync your database for the first time: python manage.py migrate ``` -We'll also create an initial user named `admin` with a password of `password123`. We'll authenticate as that user later in our example. +We'll also create an initial user named `admin` with a password of +`password123`. We'll authenticate as that user later in our example. ```text python manage.py createsuperuser ``` -Once you've set up a database and initial user created and ready to go, open up the app's directory and we'll get coding... +Once you've set up a database and initial user created 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. Let's create a new module named `tutorial/quickstart/serializers.py` that we'll use for our data representations. +First up we're going to define some serializers. Let's create a new module named +`tutorial/quickstart/serializers.py` that we'll use for our data +representations. ```python from django.contrib.auth.models import User, Group @@ -82,11 +87,14 @@ class GroupSerializer(serializers.HyperlinkedModelSerializer): fields = ('url', 'name') ``` -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. +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 write some views then. Open `tutorial/quickstart/views.py` and get typing. +Right, we'd better write some views then. Open `tutorial/quickstart/views.py` +and get typing. ```python from django.contrib.auth.models import User, Group @@ -110,9 +118,11 @@ class GroupViewSet(viewsets.ModelViewSet): serializer_class = GroupSerializer ``` -Rather than write multiple views we're grouping together all the common behavior into classes called `ViewSets`. +Rather than write multiple views we're grouping together all the common behavior +into classes called `ViewSets`. -We can easily break these down into individual views if we need to, but using viewsets keeps the view logic nicely organized as well as being very concise. +We can easily break these down into individual views if we need to, but using +viewsets keeps the view logic nicely organized as well as being very concise. ## URLs @@ -135,15 +145,21 @@ urlpatterns = [ ] ``` -Because we're using viewsets instead of views, we can automatically generate the URL conf for our API, by simply registering the viewsets with a router class. +Because we're using viewsets instead of views, we can automatically generate the +URL conf for our API, by simply registering the viewsets with a router class. -Again, if we need more control over the API URLs we can simply drop down to using regular class-based views, and writing the URL conf explicitly. +Again, if we need more control over the API URLs we can simply drop down to +using regular class-based views, and writing the URL conf explicitly. -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 browsable API. +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 browsable 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. The settings module will be in `tutorial/settings.py` +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. The settings module +will be in `tutorial/settings.py` ```python INSTALLED_APPS = ( @@ -163,11 +179,13 @@ Okay, we're done. ## Testing our API -We're now ready to test the API we've built. Let's fire up the server from the command line. +We're now ready to test the API we've built. Let's fire up the server from the +command line. python manage.py runserver -We can now access our API, both from the command-line, using tools like `curl`... +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:password123 http://127.0.0.1:8000/users/ @@ -228,15 +246,19 @@ HTTP/1.1 200 OK } ``` -Or directly through the browser, by going to the URL `http://127.0.0.1:8000/users/`... +Or directly through the browser, by going to the URL +`http://127.0.0.1:8000/users/`... ![Quick start image][image] -If you're working through the browser, make sure to login using the control in the top right corner. +If you're working through the browser, make sure to login using the control in +the top right corner. 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]. +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]. [readme-example-api]: ../#example [image]: ../img/quickstart.png