Skip to content

Commit 34b5db6

Browse files
phaltphalt
committed
Use httpie for tutorials
1 parent 270c7ac commit 34b5db6

File tree

4 files changed

+129
-23
lines changed

4 files changed

+129
-23
lines changed

‎docs/tutorial/1-serialization.md

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -332,17 +332,51 @@ Quit out of the shell...
332332

333333
In another terminal window, we can test the server.
334334

335-
We can get a list of all of the snippets.
335+
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.
336336

337-
curl http://127.0.0.1:8000/snippets/
337+
You can install httpie on all operating systems using pip:
338338

339-
[{"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"}]
339+
pip install httpie
340340

341-
Or we can get a particular snippet by referencing its id.
341+
It can also be installed through [Homebrew][brew] on Mac:
342342

343-
curl http://127.0.0.1:8000/snippets/2/
343+
brew install httpie
344344

345-
{"id": 2, "title": "", "code": "print \"hello, world\"\n", "linenos": false, "language": "python", "style": "friendly"}
345+
Finally, we can get a list of all of the snippets:
346+
347+
http http://127.0.0.1:8000/snippets/ --body
348+
349+
[
350+
{
351+
"id": 1,
352+
"title": "",
353+
"code": "foo = \"bar\"\n",
354+
"linenos": false,
355+
"language": "python",
356+
"style": "friendly"
357+
},
358+
{
359+
"id": 2,
360+
"title": "",
361+
"code": "print \"hello, world\"\n",
362+
"linenos": false,
363+
"language": "python",
364+
"style": "friendly"
365+
}
366+
]
367+
368+
Or we can get a particular snippet by referencing its id:
369+
370+
http http://127.0.0.1:8000/snippets/2/ --body
371+
372+
{
373+
"id": 2,
374+
"title": "",
375+
"code": "print \"hello, world\"\n",
376+
"linenos": false,
377+
"language": "python",
378+
"style": "friendly"
379+
}
346380

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

@@ -359,3 +393,5 @@ We'll see how we can start to improve things in [part 2 of the tutorial][tut-2].
359393
[sandbox]: http://restframework.herokuapp.com/
360394
[virtualenv]: http://www.virtualenv.org/en/latest/index.html
361395
[tut-2]: 2-requests-and-responses.md
396+
[httpie]: https://github.com/jakubroztocil/httpie#installation
397+
[brew]: http://brew.sh

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

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -127,31 +127,62 @@ Go ahead and test the API from the command line, as we did in [tutorial part 1][
127127

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

130-
curl http://127.0.0.1:8000/snippets/
131-
132-
[{"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"}]
130+
http http://127.0.0.1:8000/snippets/ --body
131+
132+
[
133+
{
134+
"id": 1,
135+
"title": "",
136+
"code": "foo = \"bar\"\n",
137+
"linenos": false,
138+
"language": "python",
139+
"style": "friendly"
140+
},
141+
{
142+
"id": 2,
143+
"title": "",
144+
"code": "print \"hello, world\"\n",
145+
"linenos": false,
146+
"language": "python",
147+
"style": "friendly"
148+
}
149+
]
133150

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

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

139156
Or by appending a format suffix:
140157

141-
curl http://127.0.0.1:8000/snippets/.json # JSON suffix
142-
curl http://127.0.0.1:8000/snippets/.api # Browsable API suffix
158+
http http://127.0.0.1:8000/snippets/.json # JSON suffix
159+
http http://127.0.0.1:8000/snippets/.api # Browsable API suffix
143160

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

146163
# POST using form data
147-
curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
164+
http --form POST http://127.0.0.1:8000/snippets/ code="print 123"
148165

149-
{"id": 3, "title": "", "code": "print 123", "linenos": false, "language": "python", "style": "friendly"}
166+
{
167+
"id": 3,
168+
"title": "",
169+
"code": "print 123",
170+
"linenos": false,
171+
"language": "python",
172+
"style": "friendly"
173+
}
150174

151175
# POST using JSON
152-
curl -X POST http://127.0.0.1:8000/snippets/ -d '{"code": "print 456"}' -H "Content-Type: application/json"
153-
154-
{"id": 4, "title": "", "code": "print 456", "linenos": true, "language": "python", "style": "friendly"}
176+
http --json POST http://127.0.0.1:8000/snippets/ code="print 456"
177+
178+
{
179+
"id": 4,
180+
"title": "",
181+
"code": "print 456",
182+
"linenos": true,
183+
"language": "python",
184+
"style": "friendly"
185+
}
155186

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

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -198,15 +198,25 @@ If we're interacting with the API programmatically we need to explicitly provide
198198

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

201-
curl -i -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
201+
http POST http://127.0.0.1:8000/snippets/ code="print 123"
202202

203-
{"detail": "Authentication credentials were not provided."}
203+
{
204+
"detail": "Authentication credentials were not provided."
205+
}
204206

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

207-
curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 789" -u tom:password
208-
209-
{"id": 5, "owner": "tom", "title": "foo", "code": "print 789", "linenos": false, "language": "python", "style": "friendly"}
209+
http POST -a tom:password http://127.0.0.1:8000/snippets/ code="print 789"
210+
211+
{
212+
"id": 5,
213+
"owner": "tom",
214+
"title": "foo",
215+
"code": "print 789",
216+
"linenos": false,
217+
"language": "python",
218+
"style": "friendly"
219+
}
210220

211221
## Summary
212222

‎docs/tutorial/quickstart.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ Create a new Django project named `tutorial`, then start a new app called `quick
2424
django-admin.py startapp quickstart
2525
cd ..
2626

27+
Optionally, install [httpie][httpie] for tastier HTTP requests:
28+
29+
pip install httpie
30+
2731
Now sync your database for the first time:
2832

2933
python manage.py migrate
@@ -159,6 +163,30 @@ We can now access our API, both from the command-line, using tools like `curl`..
159163
]
160164
}
161165

166+
Or with [httpie][httpie], a tastier version of `curl`...
167+
168+
bash: http -a username:password http://127.0.0.1:8000/users/ --body
169+
{
170+
"count": 2,
171+
"next": null,
172+
"previous": null,
173+
"results": [
174+
{
175+
"email": "[email protected]",
176+
"groups": [],
177+
"url": "http://localhost:8000/users/1/",
178+
"username": "paul"
179+
},
180+
{
181+
"email": "[email protected]",
182+
"groups": [ ],
183+
"url": "http://127.0.0.1:8000/users/2/",
184+
"username": "tom"
185+
}
186+
]
187+
}
188+
189+
162190
Or directly through the browser...
163191

164192
![Quick start image][image]
@@ -173,3 +201,4 @@ If you want to get a more in depth understanding of how REST framework fits toge
173201
[image]: ../img/quickstart.png
174202
[tutorial]: 1-serialization.md
175203
[guide]: ../#api-guide
204+
[httpie]: https://github.com/jakubroztocil/httpie#installation

0 commit comments

Comments
 (0)