From 34b5db62e560e73516fb569eaf9b71ea5562958f Mon Sep 17 00:00:00 2001 From: phalt Date: Mon, 1 Dec 2014 13:39:53 +0000 Subject: [PATCH] Use httpie for tutorials --- docs/tutorial/1-serialization.md | 48 ++++++++++++++--- docs/tutorial/2-requests-and-responses.md | 51 +++++++++++++++---- .../4-authentication-and-permissions.md | 18 +++++-- docs/tutorial/quickstart.md | 29 +++++++++++ 4 files changed, 126 insertions(+), 20 deletions(-) diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index a3c19858d..3ef651163 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -332,17 +332,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 could use `curl`, but let's use a nicer tool called [httpie][httpie] to test our server. It has much nicer formatting and makes our output easier to read. This is especially useful when testing. - curl http://127.0.0.1:8000/snippets/ +You can install httpie on all operating systems 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. +It can also be installed through [Homebrew][brew] on Mac: - curl http://127.0.0.1:8000/snippets/2/ + brew install httpie - {"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "style": "friendly"} +Finally, we can get a list of all of the snippets: + + http http://127.0.0.1:8000/snippets/ --body + + [ + { + "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/ --body + + { + "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. @@ -359,3 +393,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 +[brew]: http://brew.sh diff --git a/docs/tutorial/2-requests-and-responses.md b/docs/tutorial/2-requests-and-responses.md index f377c7122..dcaf7c0c2 100644 --- a/docs/tutorial/2-requests-and-responses.md +++ b/docs/tutorial/2-requests-and-responses.md @@ -127,31 +127,62 @@ 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/ --body - [{"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"}] + [ + { + "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]. diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md index 4e4edeeac..15d93a62a 100644 --- a/docs/tutorial/4-authentication-and-permissions.md +++ b/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 diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 1c398c1ff..41e864ccd 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -24,6 +24,10 @@ Create a new Django project named `tutorial`, then start a new app called `quick django-admin.py startapp quickstart cd .. +Optionally, install [httpie][httpie] for tastier HTTP requests: + + pip install httpie + Now sync your database for the first time: python manage.py migrate @@ -159,6 +163,30 @@ We can now access our API, both from the command-line, using tools like `curl`.. ] } +Or with [httpie][httpie], a tastier version of `curl`... + + bash: http -a username:password http://127.0.0.1:8000/users/ --body + { + "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] @@ -173,3 +201,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