encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-11-26 11:33:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Tom Christie 2014-12-08 16:38:49 +00:00
parent 61eb64ed24
commit 0cfe06f5f9
4 changed files with 122 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
tutorial/1-serialization/index.html
View File

@ -676,15 +676,47 @@ Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
</code></pre>
<p>In another terminal window, we can test the server.</p>
<p>We can get a list of all of the snippets.</p>
<pre><code>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"}]
<p>We can test our API using using <a href="http://curl.haxx.se">curl</a> or <a href="https://github.com/jakubroztocil/httpie#installation">httpie</a>. Httpie is a user friendly http client that's written in Python. Let's install that.</p>
<p>You can install httpie using pip:</p>
<pre><code>pip install httpie
</code></pre>
<p>Or we can get a particular snippet by referencing its id.</p>
<pre><code>curl http://127.0.0.1:8000/snippets/2/
<p>Finally, we can get a list of all of the snippets:</p>
<pre><code>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"
}
]
</code></pre>
<p>Or we can get a particular snippet by referencing its id:</p>
<pre><code>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"
}
</code></pre>
<p>Similarly, you can have the same json displayed by visiting these URLs in a web browser.</p>
<h2 id="where-are-we-now">Where are we now</h2>

53
tutorial/2-requests-and-responses/index.html
View File

@ -496,28 +496,61 @@ urlpatterns = format_suffix_patterns(urlpatterns)
<h2 id="hows-it-looking">How's it looking?</h2>
<p>Go ahead and test the API from the command line, as we did in <a href="../1-serialization">tutorial part 1</a>. Everything is working pretty similarly, although we've got some nicer error handling if we send invalid requests.</p>
<p>We can get a list of all of the snippets, as before.</p>
<pre><code>curl http://127.0.0.1:8000/snippets/
<pre><code>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"
}
]
</code></pre>
<p>We can control the format of the response that we get back, either by using the <code>Accept</code> header:</p>
<pre><code>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
<pre><code>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
</code></pre>
<p>Or by appending a format suffix:</p>
<pre><code>curl http://127.0.0.1:8000/snippets/.json # JSON suffix
curl http://127.0.0.1:8000/snippets/.api # Browsable API suffix
<pre><code>http http://127.0.0.1:8000/snippets/.json # JSON suffix
http http://127.0.0.1:8000/snippets/.api # Browsable API suffix
</code></pre>
<p>Similarly, we can control the format of the request that we send, using the <code>Content-Type</code> header.</p>
<pre><code># 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"
}
</code></pre>
<p>Now go and open the API in a web browser, by visiting <a href="http://127.0.0.1:8000/snippets/">http://127.0.0.1:8000/snippets/</a>.</p>
<h3 id="browsability">Browsability</h3>

18
tutorial/4-authentication-and-permissions/index.html
View File

@ -548,14 +548,24 @@ class IsOwnerOrReadOnly(permissions.BasePermission):
<p>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.</p>
<p>If we're interacting with the API programmatically we need to explicitly provide the authentication credentials on each request.</p>
<p>If we try to create a snippet without authenticating, we'll get an error:</p>
<pre><code>curl -i -X POST http://127.0.0.1:8000/snippets/ -d "code=print 123"
<pre><code>http POST http://127.0.0.1:8000/snippets/ code="print 123"
{"detail": "Authentication credentials were not provided."}
{
"detail": "Authentication credentials were not provided."
}
</code></pre>
<p>We can make a successful request by including the username and password of one of the users we created earlier.</p>
<pre><code>curl -X POST http://127.0.0.1:8000/snippets/ -d "code=print 789" -u tom:password
<pre><code>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"
}
</code></pre>
<h2 id="summary">Summary</h2>
<p>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.</p>

26
tutorial/quickstart/index.html
View File

@ -406,6 +406,7 @@ pip install djangorestframework
django-admin.py startproject tutorial .
cd tutorial
django-admin.py startapp quickstart
cd ..
</code></pre>
<p>Now sync your database for the first time:</p>
<pre><code>python manage.py migrate
@ -518,6 +519,31 @@ REST_FRAMEWORK = {
]
}
</code></pre>
<p>Or using the <a href="https://github.com/jakubroztocil/httpie#installation">httpie</a>, command line tool...</p>
<pre><code>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"
}
]
}
</code></pre>
<p>Or directly through the browser...</p>
<p><img alt="Quick start image" src="../../../img/quickstart.png" /></p>
<p>If you're working through the browser, make sure to login using the control in the top right corner.</p>