From 8a708b822e6b1a7fcc1db7222737bfca6808e57b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 14 Sep 2012 13:05:54 +0100 Subject: [PATCH] Add browseable API docs from @alecperkins --- api-guide/authentication.html | 1 + api-guide/content-negotiation.html | 1 + api-guide/exceptions.html | 1 + api-guide/format-suffixes.html | 1 + api-guide/generic-views.html | 1 + api-guide/parsers.html | 1 + api-guide/permissions.html | 1 + api-guide/renderers.html | 1 + api-guide/requests.html | 1 + api-guide/responses.html | 1 + api-guide/reverse.html | 1 + api-guide/serializers.html | 1 + api-guide/settings.html | 1 + api-guide/status-codes.html | 1 + api-guide/throttling.html | 1 + api-guide/views.html | 1 + index.html | 2 + topics/browsable-api.html | 188 ++++++++++++++++++ topics/changelog.html | 1 + topics/contributing.html | 1 + topics/credits.html | 1 + topics/csrf.html | 1 + topics/formoverloading.html | 1 + tutorial/1-serialization.html | 1 + tutorial/2-requests-and-responses.html | 7 +- tutorial/3-class-based-views.html | 1 + ...entication-permissions-and-throttling.html | 1 + .../5-relationships-and-hyperlinked-apis.html | 1 + tutorial/6-resource-orientated-projects.html | 1 + 29 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 topics/browsable-api.html diff --git a/api-guide/authentication.html b/api-guide/authentication.html index 2cdd58e10..32cd739c7 100644 --- a/api-guide/authentication.html +++ b/api-guide/authentication.html @@ -68,6 +68,7 @@ diff --git a/api-guide/content-negotiation.html b/api-guide/content-negotiation.html index e44259bf3..54254fdb4 100644 --- a/api-guide/content-negotiation.html +++ b/api-guide/content-negotiation.html @@ -68,6 +68,7 @@ diff --git a/api-guide/exceptions.html b/api-guide/exceptions.html index 19a8cd532..5a5e52d7e 100644 --- a/api-guide/exceptions.html +++ b/api-guide/exceptions.html @@ -68,6 +68,7 @@ diff --git a/api-guide/format-suffixes.html b/api-guide/format-suffixes.html index f7c8e6a96..1d481f877 100644 --- a/api-guide/format-suffixes.html +++ b/api-guide/format-suffixes.html @@ -68,6 +68,7 @@ diff --git a/api-guide/generic-views.html b/api-guide/generic-views.html index 92108e757..0181ede75 100644 --- a/api-guide/generic-views.html +++ b/api-guide/generic-views.html @@ -68,6 +68,7 @@ diff --git a/api-guide/parsers.html b/api-guide/parsers.html index bd14080f4..8210c3099 100644 --- a/api-guide/parsers.html +++ b/api-guide/parsers.html @@ -68,6 +68,7 @@ diff --git a/api-guide/permissions.html b/api-guide/permissions.html index d75a74ab1..fc4a5c004 100644 --- a/api-guide/permissions.html +++ b/api-guide/permissions.html @@ -68,6 +68,7 @@ diff --git a/api-guide/renderers.html b/api-guide/renderers.html index 09763de01..84d5dfca6 100644 --- a/api-guide/renderers.html +++ b/api-guide/renderers.html @@ -68,6 +68,7 @@ diff --git a/api-guide/requests.html b/api-guide/requests.html index 3874762a6..2ae155b75 100644 --- a/api-guide/requests.html +++ b/api-guide/requests.html @@ -68,6 +68,7 @@ diff --git a/api-guide/responses.html b/api-guide/responses.html index 609ac75d0..84b2d3be4 100644 --- a/api-guide/responses.html +++ b/api-guide/responses.html @@ -68,6 +68,7 @@ diff --git a/api-guide/reverse.html b/api-guide/reverse.html index 5f61c7274..4ba0c5004 100644 --- a/api-guide/reverse.html +++ b/api-guide/reverse.html @@ -68,6 +68,7 @@ diff --git a/api-guide/serializers.html b/api-guide/serializers.html index 58847b8c1..6ffe87992 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -68,6 +68,7 @@ diff --git a/api-guide/settings.html b/api-guide/settings.html index 6dfc9a82e..fd8725cff 100644 --- a/api-guide/settings.html +++ b/api-guide/settings.html @@ -68,6 +68,7 @@ diff --git a/api-guide/status-codes.html b/api-guide/status-codes.html index 849e65e5c..c44a54119 100644 --- a/api-guide/status-codes.html +++ b/api-guide/status-codes.html @@ -68,6 +68,7 @@ diff --git a/api-guide/throttling.html b/api-guide/throttling.html index 71be281a6..45894524b 100644 --- a/api-guide/throttling.html +++ b/api-guide/throttling.html @@ -68,6 +68,7 @@ diff --git a/api-guide/views.html b/api-guide/views.html index b37c4e8af..3dbc92400 100644 --- a/api-guide/views.html +++ b/api-guide/views.html @@ -68,6 +68,7 @@ diff --git a/index.html b/index.html index 64930eda6..5c32b1de6 100644 --- a/index.html +++ b/index.html @@ -68,6 +68,7 @@ @@ -189,6 +190,7 @@ pip install -r optionals.txt diff --git a/topics/browsable-api.html b/topics/browsable-api.html new file mode 100644 index 000000000..59aa95e46 --- /dev/null +++ b/topics/browsable-api.html @@ -0,0 +1,188 @@ + + + + Django REST framework + + + + + + + + + + + + + + +
+
+
+ GitHub + + + + + + Django REST framework +
+ + +
+
+
+
+ +
+
+
+ +
+ +
+

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 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 and Chrome.

+

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), 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. Also, there are pre-made themes available at Bootswatch. 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
    • +
  • 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 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 : The view can accept a format override
    • +
  • METHOD_PARAM : The view can accept a method override
    • +
+

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 diff --git a/topics/changelog.html b/topics/changelog.html index 4a7e9e58c..4ae8301ea 100644 --- a/topics/changelog.html +++ b/topics/changelog.html @@ -68,6 +68,7 @@ diff --git a/topics/contributing.html b/topics/contributing.html index f5154bdf1..a85911f8d 100644 --- a/topics/contributing.html +++ b/topics/contributing.html @@ -68,6 +68,7 @@ diff --git a/topics/credits.html b/topics/credits.html index 92aefc54d..d45c7cd18 100644 --- a/topics/credits.html +++ b/topics/credits.html @@ -68,6 +68,7 @@ diff --git a/topics/csrf.html b/topics/csrf.html index 0e3a49ab6..f2e50a6a8 100644 --- a/topics/csrf.html +++ b/topics/csrf.html @@ -68,6 +68,7 @@ diff --git a/topics/formoverloading.html b/topics/formoverloading.html index 7ab5fe7bb..f83977350 100644 --- a/topics/formoverloading.html +++ b/topics/formoverloading.html @@ -68,6 +68,7 @@ diff --git a/tutorial/1-serialization.html b/tutorial/1-serialization.html index d094ffc6a..78aec3d7d 100644 --- a/tutorial/1-serialization.html +++ b/tutorial/1-serialization.html @@ -68,6 +68,7 @@ diff --git a/tutorial/2-requests-and-responses.html b/tutorial/2-requests-and-responses.html index 87144f550..b297582d7 100644 --- a/tutorial/2-requests-and-responses.html +++ b/tutorial/2-requests-and-responses.html @@ -68,6 +68,7 @@ @@ -212,9 +213,11 @@ urlpatterns = format_suffix_patterns(urlpatterns)

TODO: Describe using accept headers, content-type headers, and format suffixed URLs

Now go and open the API in a web browser, by visiting http://127.0.0.1:8000/."

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 topic for more information about the browsable API feature and how to customize it.

What's next?

-

In tutorial part 3, we'll start using class based views, and see how generic views reduce the amount of code we need to write.

+

In tutorial part 3, we'll start using class based views, and see how generic views reduce the amount of code we need to write.

diff --git a/tutorial/3-class-based-views.html b/tutorial/3-class-based-views.html index 8c9fe2398..272e1d337 100644 --- a/tutorial/3-class-based-views.html +++ b/tutorial/3-class-based-views.html @@ -68,6 +68,7 @@ diff --git a/tutorial/4-authentication-permissions-and-throttling.html b/tutorial/4-authentication-permissions-and-throttling.html index a1538ed30..afb082147 100644 --- a/tutorial/4-authentication-permissions-and-throttling.html +++ b/tutorial/4-authentication-permissions-and-throttling.html @@ -68,6 +68,7 @@ diff --git a/tutorial/5-relationships-and-hyperlinked-apis.html b/tutorial/5-relationships-and-hyperlinked-apis.html index 57cb7acbd..72b2a7c92 100644 --- a/tutorial/5-relationships-and-hyperlinked-apis.html +++ b/tutorial/5-relationships-and-hyperlinked-apis.html @@ -68,6 +68,7 @@ diff --git a/tutorial/6-resource-orientated-projects.html b/tutorial/6-resource-orientated-projects.html index ebb225058..aa33ca167 100644 --- a/tutorial/6-resource-orientated-projects.html +++ b/tutorial/6-resource-orientated-projects.html @@ -68,6 +68,7 @@