From 0cfe06f5f97d57a31662760f275b984792405d6c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Dec 2014 16:38:49 +0000 Subject: [PATCH] Update documentation --- tutorial/1-serialization/index.html | 46 +++++++++++++--- tutorial/2-requests-and-responses/index.html | 53 +++++++++++++++---- .../index.html | 18 +++++-- tutorial/quickstart/index.html | 26 +++++++++ 4 files changed, 122 insertions(+), 21 deletions(-) diff --git a/tutorial/1-serialization/index.html b/tutorial/1-serialization/index.html index 292b10996..7d2d3a4d4 100644 --- a/tutorial/1-serialization/index.html +++ b/tutorial/1-serialization/index.html @@ -676,15 +676,47 @@ Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C.

In another terminal window, we can test the server.

-

We can get a list of all of the snippets.

-
curl http://127.0.0.1:8000/snippets/
-
-[{"id": 1, "title": "", "code": "foo = \"bar\"\n", "linenos": false, "language": "python", "style": "friendly"}, {"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "style": "friendly"}]
+
We can test our API using using curl or httpie. Httpie is a user friendly http client that's written in Python. Let's install that.

+
You can install httpie using pip:

+
pip install httpie
 

-
Or we can get a particular snippet by referencing its id.

-
curl http://127.0.0.1:8000/snippets/2/
+
Finally, we can get a list of all of the snippets:

+
http http://127.0.0.1:8000/snippets/
 
-{"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "style": "friendly"}
+HTTP/1.1 200 OK
+...
+[
+  {
+    "id": 1,
+    "title": "",
+    "code": "foo = \"bar\"\n",
+    "linenos": false,
+    "language": "python",
+    "style": "friendly"
+  },
+  {
+    "id": 2,
+    "title": "",
+    "code": "print \"hello, world\"\n",
+    "linenos": false,
+    "language": "python",
+    "style": "friendly"
+  }
+]
+

+
Or we can get a particular snippet by referencing its id:

+
http http://127.0.0.1:8000/snippets/2/
+
+HTTP/1.1 200 OK
+...
+{
+  "id": 2,
+  "title": "",
+  "code": "print \"hello, world\"\n",
+  "linenos": false,
+  "language": "python",
+  "style": "friendly"
+}
 

 
Similarly, you can have the same json displayed by visiting these URLs in a web browser.

 
Where are we now

diff --git a/tutorial/2-requests-and-responses/index.html b/tutorial/2-requests-and-responses/index.html
index 3ef5c3264..d7048cacf 100644
--- a/tutorial/2-requests-and-responses/index.html
+++ b/tutorial/2-requests-and-responses/index.html
@@ -496,28 +496,61 @@ urlpatterns = format_suffix_patterns(urlpatterns)
 
How's it looking?

 
Go ahead and test the API from the command line, as we did in tutorial part 1.  Everything is working pretty similarly, although we've got some nicer error handling if we send invalid requests.

 
We can get a list of all of the snippets, as before.

-
curl http://127.0.0.1:8000/snippets/
+
http http://127.0.0.1:8000/snippets/
 
-[{"id": 1, "title": "", "code": "foo = \"bar\"\n", "linenos": false, "language": "python", "style": "friendly"}, {"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "style": "friendly"}]
+HTTP/1.1 200 OK
+...
+[
+  {
+    "id": 1,
+    "title": "",
+    "code": "foo = \"bar\"\n",
+    "linenos": false,
+    "language": "python",
+    "style": "friendly"
+  },
+  {
+    "id": 2,
+    "title": "",
+    "code": "print \"hello, world\"\n",
+    "linenos": false,
+    "language": "python",
+    "style": "friendly"
+  }
+]
 

 
We can control the format of the response that we get back, either by using the Accept header:

-
curl http://127.0.0.1:8000/snippets/ -H 'Accept: application/json'  # Request JSON
-curl http://127.0.0.1:8000/snippets/ -H 'Accept: text/html'         # Request HTML
+
http http://127.0.0.1:8000/snippets/ Accept:application/json  # Request JSON
+http http://127.0.0.1:8000/snippets/ Accept:text/html         # Request HTML
 

 
Or by appending a format suffix:

-
curl http://127.0.0.1:8000/snippets/.json  # JSON suffix
-curl http://127.0.0.1:8000/snippets/.api   # Browsable API suffix
+
http http://127.0.0.1:8000/snippets/.json  # JSON suffix
+http http://127.0.0.1:8000/snippets/.api   # Browsable API suffix
 

 
Similarly, we can control the format of the request that we send, using the Content-Type header.

 
# POST using form data
-curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
+http --form POST http://127.0.0.1:8000/snippets/ code="print 123"
 
-{"id": 3, "title": "", "code": "print 123", "linenos": false, "language": "python", "style": "friendly"}
+{
+  "id": 3,
+  "title": "",
+  "code": "print 123",
+  "linenos": false,
+  "language": "python",
+  "style": "friendly"
+}
 
 # POST using JSON
-curl -X POST http://127.0.0.1:8000/snippets/ -d '{"code": "print 456"}' -H "Content-Type: application/json"
+http --json POST http://127.0.0.1:8000/snippets/ code="print 456"
 
-{"id": 4, "title": "", "code": "print 456", "linenos": true, "language": "python", "style": "friendly"}
+{
+    "id": 4,
+    "title": "",
+    "code": "print 456",
+    "linenos": true,
+    "language": "python",
+    "style": "friendly"
+}
 

 
Now go and open the API in a web browser, by visiting http://127.0.0.1:8000/snippets/.

 
Browsability

diff --git a/tutorial/4-authentication-and-permissions/index.html b/tutorial/4-authentication-and-permissions/index.html
index 2efc72453..07900eaa7 100644
--- a/tutorial/4-authentication-and-permissions/index.html
+++ b/tutorial/4-authentication-and-permissions/index.html
@@ -548,14 +548,24 @@ class IsOwnerOrReadOnly(permissions.BasePermission):
 
When we interact with the API through the web browser, we can login, and the browser session will then provide the required authentication for the requests.

 
If we're interacting with the API programmatically we need to explicitly provide the authentication credentials on each request.

 
If we try to create a snippet without authenticating, we'll get an error:

-
curl -i -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
+
http POST http://127.0.0.1:8000/snippets/ code="print 123"
 
-{"detail": "Authentication credentials were not provided."}
+{
+    "detail": "Authentication credentials were not provided."
+}
 

 
We can make a successful request by including the username and password of one of the users we created earlier.

-
curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 789" -u tom:password
+
http POST -a tom:password http://127.0.0.1:8000/snippets/ code="print 789"
 
-{"id": 5, "owner": "tom", "title": "foo", "code": "print 789", "linenos": false, "language": "python", "style": "friendly"}
+{
+    "id": 5,
+    "owner": "tom",
+    "title": "foo",
+    "code": "print 789",
+    "linenos": false,
+    "language": "python",
+    "style": "friendly"
+}
 

 
Summary

 
We've now got a fairly fine-grained set of permissions on our Web API, and end points for users of the system and for the code snippets that they have created.

diff --git a/tutorial/quickstart/index.html b/tutorial/quickstart/index.html
index f291901c9..204942b02 100644
--- a/tutorial/quickstart/index.html
+++ b/tutorial/quickstart/index.html
@@ -406,6 +406,7 @@ pip install djangorestframework
 django-admin.py startproject tutorial .
 cd tutorial
 django-admin.py startapp quickstart
+cd ..
 

 
Now sync your database for the first time:

 
python manage.py migrate
@@ -518,6 +519,31 @@ REST_FRAMEWORK = {
     ]
 }
 

+
Or using the httpie, command line tool...

+
bash: http -a username:password http://127.0.0.1:8000/users/
+
+HTTP/1.1 200 OK
+...
+{
+    "count": 2,
+    "next": null,
+    "previous": null,
+    "results": [
+        {
+            "email": "admin@example.com",
+            "groups": [],
+            "url": "http://localhost:8000/users/1/",
+            "username": "paul"
+        },
+        {
+            "email": "tom@example.com",
+            "groups": [                ],
+            "url": "http://127.0.0.1:8000/users/2/",
+            "username": "tom"
+        }
+    ]
+}
+

 
Or directly through the browser...

 
Quick start image

 
If you're working through the browser, make sure to login using the control in the top right corner.