diff options
| author | Alec Perkins | 2012-09-09 16:46:05 -0400 |
|---|---|---|
| committer | Alec Perkins | 2012-09-09 17:02:19 -0400 |
| commit | 60e6bba12b6843b01194b6534fb56129ec0b2140 (patch) | |
| tree | c456a681ecdb0e37ccde7fd2fcf59706441f262a /docs/topics | |
| parent | 7098114ac77db4909956d847a86becd4eb213e91 (diff) | |
| download | django-rest-framework-60e6bba12b6843b01194b6534fb56129ec0b2140.tar.bz2 | |
Browsable API doc topic
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/browsable-api.md | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md new file mode 100644 index 00000000..6d2d2a37 --- /dev/null +++ b/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.
\ No newline at end of file |