diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/browsable-api.md | 62 | ||||
| -rw-r--r-- | docs/topics/credits.md | 2 | ||||
| -rw-r--r-- | docs/topics/documenting-your-api.md | 112 | ||||
| -rw-r--r-- | docs/topics/rest-hypermedia-hateoas.md | 3 |
4 files changed, 156 insertions, 23 deletions
diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index dcba9b0a..85f1faff 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -11,69 +11,85 @@ API may stand for Application *Programming* Interface, but humans have to be abl If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `rest_framework` package includes a [`reverse`][drfreverse] 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][ffjsonview] and [Chrome][chromejsonview]. - ## Customizing -To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/rest_framework/api.html`, that extends the `rest_framework/base.html` template. +The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 2.1.1), making it easy to customize the look-and-feel. + +To customize the default style, create a template called `rest_framework/api.html` that extends from `rest_framework/base.html`. For example: -The included browsable API template is built with [Bootstrap (2.1.1)][bootstrap], making it easy to customize the look-and-feel. +**templates/rest_framework/api.html** + + {% extends "rest_framework/base.html" %} + + ... # Override blocks with required customizations -### Theme +### Overriding the default 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. +To replace the default theme, 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][bcustomize]. Also, there are pre-made themes available at [Bootswatch][bswatch]. 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. +A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. There are also pre-made themes available at [Bootswatch][bswatch]. 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. -Full Example +Full example: {% extends "rest_framework/base.html" %} {% block bootstrap_theme %} - <link rel="stylesheet" href="/path/to/yourtheme/bootstrap.min.css' type="text/css"> + <link rel="stylesheet" href="http://bootswatch.com/flatly/bootstrap.min.css" type="text/css"> {% endblock %} {% block bootstrap_navbar_variant %}{% endblock %} +For more specific CSS tweaks than simply overriding the default bootstrap theme you can override the `style` block. + +--- + +![Cerulean theme][cerulean] + +*Screenshot of the bootswatch 'Cerulean' theme* + +--- + +![Slate theme][slate] -For more specific CSS tweaks, use the `style` block instead. +*Screenshot of the bootswatch 'Slate' theme* +--- ### Blocks All of the blocks available in the browsable API base template that can be used in your `api.html`. -* `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][bcomponentsnav] +* `bodyclass` - Class attribute for the `<body>` tag, empty by default. +* `bootstrap_theme` - CSS for the Bootstrap theme. +* `bootstrap_navbar_variant` - CSS class for the navbar. +* `branding` - Branding section of the navbar, see [Bootstrap components][bcomponentsnav]. * `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. -* `footer` - Any copyright notices or similar footer materials can go here (by default right-aligned) -* `style` - CSS stylesheets for the page -* `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. +* `footer` - Any copyright notices or similar footer materials can go here (by default right-aligned). +* `style` - CSS stylesheets for the page. +* `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][bcomponents] are available. +All of the standard [Bootstrap components][bcomponents] are available. -##### Tooltips +#### 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. +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 will display a tooltip on hover events. ### Login Template -To add branding and customize the look-and-feel of the auth login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`, that extends the `rest_framework/base_login.html` template. +To add branding and customize the look-and-feel of the login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`. The template should extend from `rest_framework/base_login.html`. You can add your site name or branding by including the branding block: @@ -114,6 +130,8 @@ For more advanced customization, such as not having a Bootstrap basis or tighter [ffjsonview]: https://addons.mozilla.org/en-US/firefox/addon/jsonview/ [chromejsonview]: https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc [bootstrap]: http://getbootstrap.com +[cerulean]: ../img/cerulean.png +[slate]: ../img/slate.png [bcustomize]: http://twitter.github.com/bootstrap/customize.html#variables [bswatch]: http://bootswatch.com/ [bcomponents]: http://twitter.github.com/bootstrap/components.html diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 94760c74..e6fb9134 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -144,6 +144,7 @@ The following people have helped make REST framework great. * David Sanders - [davesque] * Philip Douglas - [freakydug] * Igor Kalat - [trwired] +* Rudolf Olah - [omouse] Many thanks to everyone who's contributed to the project. @@ -324,3 +325,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [davesque]: https://github.com/davesque [freakydug]: https://github.com/freakydug [trwired]: https://github.com/trwired +[omouse]: https://github.com/omouse diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md new file mode 100644 index 00000000..7ee538f5 --- /dev/null +++ b/docs/topics/documenting-your-api.md @@ -0,0 +1,112 @@ +# Documenting your API + +> A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state. +> +> — Roy Fielding, [REST APIs must be hypertext driven][cite] + +There are a variety of approaches to API documentation. This document introduces a few of the various tools and options you might choose from. The approaches should not be considered exclusive - you may want to provide more than one documentation style for you API, such as a self describing API that also includes static documentation of the various API endpoints. + +## Endpoint documentation + +The most common way to document Web APIs today is to produce documentation that lists the API endpoints verbatim, and describes the allowable operations on each. There are various tools that allow you to do this in an automated or semi-automated way. + +--- + +#### Django REST Swagger + +Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints. + +The pacakge is fully documented, well supported, and comes highly recommended. + +Django REST Swagger supports REST framework versions 2.3 and above. + +![Screenshot - Django REST Swagger][image-django-rest-swagger] + +--- + +#### REST Framework Docs + +The [REST Framework Docs][rest-framework-docs] package is an earlier project, also by Marc Gibbons, that offers clean, simple autogenerated documentation for your API. + +![Screenshot - REST Framework Docs][image-rest-framework-docs] + +--- + +#### Apiary + +There are various other online tools and services for providing API documentation. One notable service is [Apiary][apiary]. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing & prototyping, and various other tools. + +![Screenshot - Apiary][image-apiary] + +--- + +## Self describing APIs + +The browsable API that REST framwork provides makes it possible for your API to be entirely self describing. The documentation for each API endpoint can be provided simply by visiting the URL in your browser. + +![Screenshot - Self describing API][image-self-describing-api] + +--- + +#### Setting the title + +The title that is used in the browsable API is generated from the view class name or function name. Any trailing `View` or `ViewSet` suffix is stripped, and the string is whitespace separated on uppercase/lowercase boundaries or underscores. + +For example, the view `UserListView`, will be named `User List` when presented in the browsable API. + +When working with viewsets, an appropriate suffix is appended to each generated view. For example, the view set `UserViewSet` will generate views named `User List` and `User Instance`. + +#### Setting the description + +The description in the browsable API is generated from the docstring of the view or viewset. + +If the python `markdown` library is installed, then [markdown syntax][markdown] may be used in the docstring, and will be converted to HTML in the browsable API. For example: + + class AccountListView(views.APIView): + """ + Returns a list of all **active** accounts in the system. + + For more details on how accounts are activated please [see here][ref]. + + [ref]: http://example.com/activating-accounts + """ + +Note that one constraint of using viewsets is that any documentation be used for all generated views, so for example, you cannot have differing documentation for the generated list view and detail view. + +#### The `OPTIONS` method + +REST framework APIs also support programmatically accessible descriptions, using the `OPTIONS` HTTP method. A view will respond to an `OPTIONS` request with metadata including the name, description, and the various media types it accepts and responds with. + +When using the generic views, any `OPTIONS` requests will additionally respond with metadata regarding any `POST` or `PUT` actions available, describing which fields are on the serializer. + +You can modify the response behavior to `OPTIONS` requests by overriding the `metadata` view method. For example: + + def metadata(self, request): + """ + Don't include the view description in OPTIONS responses. + """ + data = super(ExampleView, self).metadata(request) + data.pop('description') + return data + +--- + +## The hypermedia approach + +To be fully RESTful an API should present it's available actions as hypermedia controls in the responses that it sends. + +In this approach, rather than documenting the available API endpoints up front, the description instead concentrates on the *media types* that are used. The available actions take may be taken on any given URL are not strictly fixed, but are instead made available by the presence of link and form controls in the returned document. + +To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documention includes pointers to background reading, as well as links to various hypermedia formats. + +[cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger +[swagger]: https://developers.helloreverb.com/swagger/ +[rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs +[apiary]: http://apiary.io/ +[markdown]: http://daringfireball.net/projects/markdown/ +[hypermedia-docs]: rest-hypermedia-hateoas.md +[image-django-rest-swagger]: ../img/django-rest-swagger.png +[image-rest-framework-docs]: ../img/rest-framework-docs.png +[image-apiary]: ../img/apiary.png +[image-self-describing-api]: ../img/self-describing.png diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index b4899a36..3d700488 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ## What REST framework doesn't provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [HAL][hal], [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [HAL][hal], [Collection+JSON][collection], [JSON API][json-api] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm @@ -46,6 +46,7 @@ What REST framework doesn't do is give you is machine readable hypermedia format [hal]: http://stateless.co/hal_specification.html [collection]: http://www.amundsen.com/media-types/collection/ +[json-api]: http://jsonapi.org/ [microformats]: http://microformats.org/wiki/Main_Page [serialization]: ../api-guide/serializers.md [parser]: ../api-guide/parsers.md |