Browsable API doc topic

docs/index.md

@@ -94,6 +94,7 @@ General guides to using REST framework.
 
 * [CSRF][csrf]
 * [Form overloading][formoverloading]
+* [Working with the Browsable API][browsableapi]
 * [Contributing to REST framework][contributing]
 * [Credits][credits]
 
@@ -162,5 +163,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 [csrf]: topics/csrf.md
 [formoverloading]: topics/formoverloading.md
+[browsableapi]: topics/browsable-api.md
 [contributing]: topics/contributing.md
 [credits]: topics/credits.md

docs/template.html

@@ -64,6 +64,7 @@
                 <ul class="dropdown-menu">
                   <li><a href="{{ base_url }}/topics/csrf{{ suffix }}">Working with AJAX and CSRF</a></li>
                   <li><a href="{{ base_url }}/topics/formoverloading{{ suffix }}">Browser based PUT, PATCH and DELETE</a></li>
+                  <li><a href="{{ base_url }}/topics/browsable-api{{ suffix }}">Working with the browsable API</a></li>
                   <li><a href="{{ base_url }}/topics/contributing{{ suffix }}">Contributing to REST framework</a></li>
                   <li><a href="{{ base_url }}/topics/credits{{ suffix }}">Credits</a></li>
                 </ul>

docs/topics/browsable-api.md

@@ -0,0 +1,86 @@
+# Working with the Browsable API
+
+API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`.
+
+## URLs
+
+If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `djangorestframework` package includes a [`reverse`](../api-guide/reverse.md) helper for this purpose.
+
+
+## Formats
+
+By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jsonview/) and [Chrome](https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc).
+
+
+## Customizing
+
+To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/djangorestframework/api.html`, that extends the `djangorestframework/base.html` template.
+
+The included browsable API template is built with [Bootstrap (2.1.1)](http://getbootstrap.com), making it easy to customize the look-and-feel.
+
+### Theme
+
+To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme.
+
+    {% block bootstrap_theme %}
+        <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
+    {% endblock %}
+
+A suitable replacement theme can be generated using Bootstrap's [Customize Tool](http://twitter.github.com/bootstrap/customize.html#variables). Also, there are pre-made themes available at [Bootswatch](http://bootswatch.com/), which are even hosted by [Bootstrap CDN](http://www.bootstrapcdn.com/). To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above.
+
+You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style.
+
+For more specific CSS tweaks, use the `extra_style` block instead.
+
+
+### Blocks
+
+All of the blocks available in the browsable API base template that can be used in your `api.html`.
+
+* `blockbots`                  - `<meta>` tag that blocks crawlers
+* `bodyclass`                  - (empty) class attribute for the `<body>`
+* `bootstrap_theme`            - CSS for the Bootstrap theme
+* `bootstrap_navbar_variant`   - CSS class for the navbar
+* `branding`                   - section of the navbar, see [Bootstrap components](http://twitter.github.com/bootstrap/components.html#navbar)
+* `breadcrumbs`                - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block.
+* `extrastyle`                 - (empty) extra CSS for the page
+* `extrahead`                  - (empty) extra markup for the page `<head>`
+* `footer`                     - Any copyright notices or similar footer materials can go here (by default right-aligned)
+* `global_heading`             - (empty) Use to insert content below the header but before the breadcrumbs.
+* `title`                      - title of the page
+* `userlinks`                  - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use {{ block.super }} to preserve the authentication links.
+
+#### Components
+
+All of the [Bootstrap components](http://twitter.github.com/bootstrap/components.html) are available.
+
+##### Tooltips
+
+The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content displayed in a tooltip on hover after a 1000ms delay.
+
+
+### Advanced Customization
+
+#### Context
+
+The context that's available to the template:
+
+* `allowed_methods`     : A list of methods allowed by the resource
+* `api_settings`        : The API settings
+* `available_formats`   : A list of formats allowed by the resource
+* `breadcrumblist`      : The list of links following the chain of nested resources
+* `content`             : The content of the API response
+* `description`         : The description of the resource, generated from its docstring
+* `name`                : The name of the resource
+* `post_form`           : A form instance for use by the POST form (if allowed)
+* `put_form`            : A form instance for use by the PUT form (if allowed)
+* `request`             : The request object
+* `response`            : The response object
+* `version`             : The version of Django REST Framework
+* `view`                : The view handling the request
+* `FORMAT_PARAM`        : self._FORMAT_QUERY_PARAM
+* `METHOD_PARAM`        : getattr(self.view, '_METHOD_PARAM', None)
+
+#### Not using base.html
+
+For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you.

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

@@ -133,7 +133,12 @@ Now go and open the API in a web browser, by visiting [http://127.0.0.1:8000/][3
 
 **Note: Right now the Browseable API only works with the CBV's.  Need to fix that.**
 
-**TODO: Describe browseable API awesomeness**
+### Browsability
+
+Because the API chooses a return format based on what the client asks for, it will, by default, return an HTML-formatted representation of the resource when that resource is requested by a browser. This allows for the API to be easily browsable and usable by humans.
+
+See the [browsable api][4] topic for more information about the browsable API feature and how to customize it.
+
 
 ## What's next?
 
@@ -142,4 +147,5 @@ In [tutorial part 3][4], we'll start using class based views, and see how generi
 [json-url]: http://example.com/api/items/4.json
 [2]: 1-serialization.md
 [3]: http://127.0.0.1:8000/
-[4]: 3-class-based-views.md
+[4]: ../topics/browsable-api.md
+[5]: 3-class-based-views.md