diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.md | 21 | ||||
| -rw-r--r-- | docs/template.html | 2 | ||||
| -rw-r--r-- | docs/topics/browser-enhancements.md | 49 | ||||
| -rw-r--r-- | docs/topics/credits.md | 6 | ||||
| -rw-r--r-- | docs/topics/rest-framework-2-announcement.md | 18 | ||||
| -rw-r--r-- | docs/tutorial/1-serialization.md | 10 | ||||
| -rw-r--r-- | docs/tutorial/5-relationships-and-hyperlinked-apis.md | 20 |
7 files changed, 102 insertions, 24 deletions
diff --git a/docs/index.md b/docs/index.md index 4126fc77..a96d0925 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,12 +5,24 @@ **A toolkit for building well-connected, self-describing Web APIs.** -**WARNING: This documentation is for the 2.0 redesign of REST framework. It is a work in progress.** +--- + +**Note**: This documentation is for the 2.0 version of REST framework. If you are looking for earlier versions please see the [0.4.x branch][0.4] on GitHub. + +--- Django REST framework is a lightweight library that makes it easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. Web APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. +If you are considering using REST framework for your API, we recommend reading the [REST framework 2 announcment][rest-framework-2-announcement] which gives a good overview of the framework and it's capabilities. + +There is also a sandbox API you can use for testing purposes, [available here][sandbox]. + +**Below**: *Screenshot from the browseable API* + +![Screenshot][image] + ## Requirements REST framework requires the following: @@ -25,8 +37,6 @@ The following packages are optional: ## Installation -**WARNING: These instructions will only become valid once this becomes the master version** - Install using `pip`, including any optional packages you want... pip install djangorestframework @@ -56,9 +66,11 @@ If you're intending to use the browseable API you'll want to add REST framework' Note that the URL path can be whatever you want, but you must include `rest_framework.urls` with the `rest_framework` namespace. +<!-- ## Quickstart Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running with REST framework. +--> ## Tutorial @@ -152,6 +164,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [urlobject]: https://github.com/zacharyvoase/urlobject [markdown]: http://pypi.python.org/pypi/Markdown/ [yaml]: http://pypi.python.org/pypi/PyYAML +[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X +[image]: img/quickstart.png +[sandbox]: http://restframework.herokuapp.com/ [quickstart]: tutorial/quickstart.md [tut-1]: tutorial/1-serialization.md diff --git a/docs/template.html b/docs/template.html index fcceede5..08387968 100644 --- a/docs/template.html +++ b/docs/template.html @@ -53,7 +53,7 @@ <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a> <ul class="dropdown-menu"> - <li><a href="{{ base_url }}/tutorial/quickstart{{ suffix }}">Quickstart</a></li> + <!--<li><a href="{{ base_url }}/tutorial/quickstart{{ suffix }}">Quickstart</a></li>--> <li><a href="{{ base_url }}/tutorial/1-serialization{{ suffix }}">1 - Serialization</a></li> <li><a href="{{ base_url }}/tutorial/2-requests-and-responses{{ suffix }}">2 - Requests and responses</a></li> <li><a href="{{ base_url }}/tutorial/3-class-based-views{{ suffix }}">3 - Class based views</a></li> diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index d4e128ae..6a11f0fa 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -2,42 +2,63 @@ > "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" > -> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. +> — [RESTful Web Services][cite], Leonard Richardson & Sam Ruby. ## Browser based PUT, DELETE, etc... -**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). +REST framework supports browser-based `PUT`, `DELETE` and other methods, by +overloading `POST` requests using a hidden form field. + +Note that this is the same strategy as is used in [Ruby on Rails][rails]. For example, given the following form: <form action="/news-items/5" method="POST"> - <input type="hidden" name="_method" value="DELETE"> - </form> + <input type="hidden" name="_method" value="DELETE"> + </form> `request.method` would return `"DELETE"`. ## Browser based submission of non-form content -Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: +Browser-based submission of content types other than form are supported by +using form fields named `_content` and `_content_type`: For example, given the following form: <form action="/news-items/5" method="PUT"> - <input type="hidden" name="_content_type" value="application/json"> - <input name="_content" value="{'count': 1}"> - </form> + <input type="hidden" name="_content_type" value="application/json"> + <input name="_content" value="{'count': 1}"> + </form> -`request.content_type` would return `"application/json"`, and `request.stream` would return `"{'count': 1}"` +`request.content_type` would return `"application/json"`, and +`request.stream` would return `"{'count': 1}"` ## URL based accept headers +REST framework can take `?accept=application/json` style URL parameters, +which allow the `Accept` header to be overridden. + +This can be useful for testing the API from a web browser, where you don't +have any control over what is sent in the `Accept` header. + ## URL based format suffixes +REST framework can take `?format=json` style URL parameters, which can be a +useful shortcut for determing which content type should be returned from +the view. + +This is a more concise than using the `accept` override, but it also gives +you less control. (For example you can't specify any media type parameters) + ## Doesn't HTML5 support PUT and DELETE forms? -Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but +was later [dropped from the spec][html5]. There remains +[ongoing discussion][put_delete] about adding support for `PUT` and `DELETE`, +as well as how to support content types other than form-encoded data. -[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 -[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 -[4]: http://amundsen.com/examples/put-delete-forms/ +[cite]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[rails]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[html5]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[put_delete]: http://amundsen.com/examples/put-delete-forms/ diff --git a/docs/topics/credits.md b/docs/topics/credits.md index a317afde..69d57802 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -50,6 +50,7 @@ The following people have helped make REST framework great. * Rob Dobson - [rdobson] * Daniel Vaca Araujo - [diviei] * Madis Väin - [madisvain] +* Stephan Groß - [minddust] Many thanks to everyone who's contributed to the project. @@ -61,6 +62,8 @@ Project hosting is with [GitHub]. Continuous integration testing is managed with [Travis CI][travis-ci]. +The [live sandbox][sandbox] is hosted on [Heroku]. + Various inspiration taken from the [Piston], [Tastypie] and [Dagny] projects. Development of REST framework 2.0 was sponsored by [DabApps]. @@ -82,6 +85,8 @@ To contact the author directly: [tastypie]: https://github.com/toastdriven/django-tastypie [dagny]: https://github.com/zacharyvoase/dagny [dabapps]: http://lab.dabapps.com +[sandbox]: http://restframework.herokuapp.com/ +[heroku]: http://www.heroku.com/ [tomchristie]: https://github.com/tomchristie [markotibold]: https://github.com/markotibold @@ -131,3 +136,4 @@ To contact the author directly: [rdobson]: https://github.com/rdobson [diviei]: https://github.com/diviei [madisvain]: https://github.com/madisvain +[minddust]: https://github.com/minddust
\ No newline at end of file diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index 82e8fe36..885d1918 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -1,12 +1,18 @@ # Django REST framework 2 -What it is, and why you should care +What it is, and why you should care. > Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. > > — [Roy Fielding][cite] -REST framework 2 is an almost complete reworking of the original framework, which comprehensivly addresses some of the original design issues. +--- + +**Announcement:** REST framework 2 released - Tue 30th Oct 2012 + +--- + +REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses some of the original design issues. Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0. @@ -74,15 +80,21 @@ There are also some functionality improvments - actions such as as `POST` and `D As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. -We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making. +We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. ## Summary In short, we've engineered the hell outta this thing, and we're incredibly proud of the result. +If you're interested please take a browse around the documentation. [The tutorial][tut] is a great place to get started. + +There's also a [live sandbox version of the tutorial API][sandbox] available for testing. + [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724 [quote1]: https://twitter.com/kobutsu/status/261689665952833536 [quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J [quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ [image]: ../img/quickstart.png [readthedocs]: https://readthedocs.org/ +[tut]: ../tutorial/1-serialization.md +[sandbox]: http://restframework.herokuapp.com/ diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 0b84a779..5cf16a67 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -4,7 +4,13 @@ This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together. -The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the [quickstart] documentation instead. +The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started.<!-- If you just want a quick overview, you should head over to the [quickstart] documentation instead. --> + +--- + +**Note**: The final code for this tutorial is available in the [tomchristie/rest-framework-tutorial][repo] repository on GitHub. There is also a sandbox version for testing, [available here][sandbox]. + +--- ## Setting up a new environment @@ -303,5 +309,7 @@ Our API views don't do anything particularly special at the moment, beyond serve We'll see how we can start to improve things in [part 2 of the tutorial][tut-2]. [quickstart]: quickstart.md +[repo]: https://github.com/tomchristie/rest-framework-tutorial +[sandbox]: http://restframework.herokuapp.com/ [virtualenv]: http://www.virtualenv.org/en/latest/index.html [tut-2]: 2-requests-and-responses.md diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md index 38e32157..1f663745 100644 --- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md +++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md @@ -74,7 +74,7 @@ We can easily re-write our existing serializers to use hyperlinking. class SnippetSerializer(serializers.HyperlinkedModelSerializer): owner = serializers.Field(source='owner.username') - highlight = serializers.HyperlinkedIdentityField(view_name='snippet-highlight') + highlight = serializers.HyperlinkedIdentityField(view_name='snippet-highlight', format='html') class Meta: model = models.Snippet @@ -91,6 +91,8 @@ We can easily re-write our existing serializers to use hyperlinking. Notice that we've also added a new `'highlight'` field. This field is of the same type as the `url` field, except that it points to the `'snippet-highlight'` url pattern, instead of the `'snippet-detail'` url pattern. +Because we've included format suffixed URLs such as `'.json'`, we also need to indicate on the `highlight` field that any format suffixed hyperlinks it returns should use the `'.html'` suffix. + ## Making sure our URL patterns are named If we're going to have a hyperlinked API, we need to make sure we name our URL patterns. Let's take a look at which URL patterns we need to name. @@ -128,6 +130,20 @@ After adding all those names into our URLconf, our final `'urls.py'` file should namespace='rest_framework')) ) +## Adding pagination + +The list views for users and code snippets could end up returning quite a lot of instances, so really we'd like to make sure we paginate the results, and allow the API client to step through each of the individual pages. + +We can change the default list style to use pagination, by modifying our `settings.py` file slightly. Add the following setting: + + REST_FRAMEWORK = { + 'PAGINATE_BY': 10 + } + +Note that settings in REST framework are all namespaced into a single dictionary setting, named 'REST_FRAMEWORK', which helps keep them well seperated from your other project settings. + +We could also customize the pagination style if we needed too, but in this case we'll just stick with the default. + ## Reviewing our work If we open a browser and navigate to the browseable API, you'll find that you can now work your way around the API simply by following links. @@ -151,7 +167,7 @@ We've reached the end of our tutorial. If you want to get more involved in the **Now go build some awesome things.** [repo]: https://github.com/tomchristie/rest-framework-tutorial -[sandbox]: http://sultry-coast-6726.herokuapp.com/ +[sandbox]: http://restframework.herokuapp.com/ [github]: https://github.com/tomchristie/django-rest-framework [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [twitter]: https://twitter.com/_tomchristie
\ No newline at end of file |