Merge pull request #2165 from phalt/httpie-examples

Use httpie for tutorials

docs/tutorial/1-serialization.md

@@ -326,17 +326,51 @@ Quit out of the shell...
 
 In another terminal window, we can test the server.
 
-We can get a list of all of the snippets.
+We can test our API using using [curl][curl] or [httpie][httpie]. Httpie is a user friendly http client that's written in Python. Let's install that.
 
-	curl http://127.0.0.1:8000/snippets/
+You can install httpie using pip:
 
-	[{"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"}]
+    pip install httpie
 
-Or we can get a particular snippet by referencing its id.
+Finally, we can get a list of all of the snippets:
 
-	curl http://127.0.0.1:8000/snippets/2/
+    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.
 
@@ -353,3 +387,5 @@ We'll see how we can start to improve things in [part 2 of the tutorial][tut-2].
 [sandbox]: http://restframework.herokuapp.com/
 [virtualenv]: http://www.virtualenv.org/en/latest/index.html
 [tut-2]: 2-requests-and-responses.md
+[httpie]: https://github.com/jakubroztocil/httpie#installation
+[curl]: http://curl.haxx.se

docs/tutorial/2-requests-and-responses.md

@@ -127,31 +127,64 @@ Go ahead and test the API from the command line, as we did in [tutorial part 1][
 
 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/][devserver].
 

docs/tutorial/4-authentication-and-permissions.md

@@ -198,15 +198,25 @@ If we're interacting with the API programmatically we need to explicitly provide
 
 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
 

docs/tutorial/quickstart.md

@@ -158,6 +158,33 @@ We can now access our API, both from the command-line, using tools like `curl`..
         ]
     }
 
+Or using the [httpie][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][image]
@@ -172,3 +199,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
+[httpie]: https://github.com/jakubroztocil/httpie#installation