Schemas & client libraries.

docs/index.md

@@ -292,6 +292,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [tut-4]: tutorial/4-authentication-and-permissions.md
 [tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md
 [tut-6]: tutorial/6-viewsets-and-routers.md
+[tut-7]: tutorial/7-schemas-and-client-libraries.md
 
 [request]: api-guide/requests.md
 [response]: api-guide/responses.md

docs/tutorial/6-viewsets-and-routers.md

@@ -130,27 +130,7 @@ Using viewsets can be a really useful abstraction.  It helps ensure that URL con
 
 That doesn't mean it's always the right approach to take.  There's a similar set of trade-offs to consider as when using class-based views instead of function based views.  Using viewsets is less explicit than building your views individually.
 
-## Reviewing our work
+In [part 7][tut-7] of the tutorial we'll look at how we can add an API schema,
+and interact with our API using a client library or command line tool.
 
-With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browsable, and comes complete with authentication, per-object permissions, and multiple renderer formats.
-
-We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views.
-
-You can review the final [tutorial code][repo] on GitHub, or try out a live example in [the sandbox][sandbox].
-
-## Onwards and upwards
-
-We've reached the end of our tutorial.  If you want to get more involved in the REST framework project, here are a few places you can start:
-
-* Contribute on [GitHub][github] by reviewing and submitting issues, and making pull requests.
-* Join the [REST framework discussion group][group], and help build the community.
-* Follow [the author][twitter] on Twitter and say hi.
-
-**Now go build awesome things.**
-
-
-[repo]: https://github.com/tomchristie/rest-framework-tutorial
-[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
+[tut-7]: 7-schemas-and-client-libraries.md

docs/tutorial/7-schemas-and-client-libraries.md

@@ -0,0 +1,216 @@
+# Tutorial 7: Schemas & client libraries
+
+A schema is a machine-readable document that describes the available API
+endpoints, their URLS, and what operations they support.
+
+Schemas can be a useful tool for auto-generated documentation, and can also
+be used to drive dynamic client libraries that can interact with the API.
+
+## Core API
+
+In order to provide schema support REST framework uses [Core API][coreapi].
+
+Core API is a document specification for describing APIs. It is used to provide
+an internal representation format of the available endpoints and possible
+interactions that an API exposes. It can either be used server-side, or
+client-side.
+
+When used server-side, Core API allows an API to support rendering to a wide
+range of schema or hypermedia formats.
+
+When used client-side, Core API allows for dynamically driven client libraries
+that can interact with any API that exposes a supported schema or hypermedia
+format.
+
+## Adding a schema
+
+REST framework supports either explicitly defined schema views, or
+automatically generated schemas. Since we're using viewsets and routers,
+we can simply use the automatic schema generation.
+
+You'll need to install the `coreapi` python package in order to include an
+API schema.
+
+    $ pip install coreapi
+
+We can now include a schema for our API, by adding a `schema_title` argument to
+the router instantiation.
+
+    router = DefaultRouter(schema_title='Pastebin API')
+
+If you visit the API root endpoint in a browser you should now see `corejson`
+representation become available as an option.
+
+![Schema format](../img/corejson-format.png)
+
+We can also request the schema from the command line, by specifying the desired
+content type in the `Accept` header.
+
+    $ http http://127.0.0.1:8000/ Accept:application/vnd.coreapi+json
+    HTTP/1.0 200 OK
+    Allow: GET, HEAD, OPTIONS
+    Content-Type: application/vnd.coreapi+json
+
+    {
+        "_meta": {
+            "title": "Pastebin API"
+        },
+        "_type": "document",
+        ...
+
+The default output style is to use the [Core JSON][corejson] encoding.
+
+Other schema formats, such as [Open API][openapi] (formerly Swagger) are
+also supported.
+
+## Using a command line client
+
+Now that our API is exposing a schema endpoint, we can use a dynamic client
+library to interact with the API. To demonstrate this, let's use the
+Core API command line client. We've already installed the `coreapi` package
+using `pip`, so the client tool should already be installed. Check that it
+is available on the command line...
+
+    $ coreapi
+    Usage: coreapi [OPTIONS] COMMAND [ARGS]...
+
+      Command line client for interacting with CoreAPI services.
+
+      Visit http://www.coreapi.org for more information.
+
+    Options:
+      --version  Display the package version number.
+      --help     Show this message and exit.
+
+    Commands:
+    ...
+
+First we'll load the API schema using the command line client.
+
+    $ coreapi get http://127.0.0.1:8000/
+    <Pastebin API "http://127.0.0.1:8000/">
+        snippets: {
+            highlight(pk)
+            list()
+            retrieve(pk)
+        }
+        users: {
+            list()
+            retrieve(pk)
+        }
+
+We haven't authenticated yet, so right now we're only able to see the read only
+endpoints, in line with how we've set up the permissions on the API.
+
+Let's try listing the existing snippets, using the command line client:
+
+    $ coreapi action snippets list
+    [
+        {
+            "url": "http://127.0.0.1:8000/snippets/1/",
+            "highlight": "http://127.0.0.1:8000/snippets/1/highlight/",
+            "owner": "lucy",
+            "title": "Example",
+            "code": "print('hello, world!')",
+            "linenos": true,
+            "language": "python",
+            "style": "friendly"
+        },
+        ...
+
+Some of the API endpoints require named parameters. For example, to get back
+the highlight HTML for a particular snippet we need to provide an id.
+
+    $ coreapi action snippets highlight --param pk 1
+    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+
+    <html>
+    <head>
+      <title>Example</title>
+      ...
+
+## Authenticating our client
+
+If we want to be able to create, edit and delete snippets, we'll need to
+authenticate as a valid user. In this case we'll just use basic auth.
+
+Make sure to replace the `<username>` and `<password>` below with your
+actual username and password.
+
+    $ coreapi credentials add 127.0.0.1 <username>:<password> --auth basic
+    Added credentials
+    127.0.0.1 "Basic <...>"
+
+Now if we fetch the schema again, we should be able to see the full
+set of available interactions.
+
+    $ coreapi reload
+    Pastebin API "http://127.0.0.1:8000/">
+        snippets: {
+            create(code, [title], [linenos], [language], [style])
+            destroy(pk)
+            highlight(pk)
+            list()
+            partial_update(pk, [title], [code], [linenos], [language], [style])
+            retrieve(pk)
+            update(pk, code, [title], [linenos], [language], [style])
+        }
+        users: {
+            list()
+            retrieve(pk)
+        }
+
+We're now able to interact with these endpoints. For example, to create a new
+snippet:
+
+    $ coreapi action snippets create --param title "Example" --param code "print('hello, world')"
+    {
+        "url": "http://127.0.0.1:8000/snippets/7/",
+        "id": 7,
+        "highlight": "http://127.0.0.1:8000/snippets/7/highlight/",
+        "owner": "lucy",
+        "title": "Example",
+        "code": "print('hello, world')",
+        "linenos": false,
+        "language": "python",
+        "style": "friendly"
+    }
+
+And to delete a snippet:
+
+    $ coreapi action snippets destroy --param pk 7
+
+As well as the command line client, developers can also interact with your
+API using client libraries. The Python client library is the first of these
+to be available, and a Javascript client library is planned to be released
+soon.
+
+For more details on customizing schema generation and using Core API
+client libraries you'll need to refer to the full documentation.
+
+## Reviewing our work
+
+With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browsable, includes a schema-driven client library, and comes complete with authentication, per-object permissions, and multiple renderer formats.
+
+We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views.
+
+You can review the final [tutorial code][repo] on GitHub, or try out a live example in [the sandbox][sandbox].
+
+## Onwards and upwards
+
+We've reached the end of our tutorial.  If you want to get more involved in the REST framework project, here are a few places you can start:
+
+* Contribute on [GitHub][github] by reviewing and submitting issues, and making pull requests.
+* Join the [REST framework discussion group][group], and help build the community.
+* Follow [the author][twitter] on Twitter and say hi.
+
+**Now go build awesome things.**
+
+[coreapi]: http://www.coreapi.org
+[corejson]: http://www.coreapi.org/specification/encoding/#core-json-encoding
+[openapi]: https://openapis.org/
+[repo]: https://github.com/tomchristie/rest-framework-tutorial
+[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

mkdocs.yml

@@ -20,6 +20,7 @@ pages:
     - '4 - Authentication and permissions': 'tutorial/4-authentication-and-permissions.md'
     - '5 - Relationships and hyperlinked APIs': 'tutorial/5-relationships-and-hyperlinked-apis.md'
     - '6 - Viewsets and routers': 'tutorial/6-viewsets-and-routers.md'
+    - '7 - Schemas and client libraries': 'tutorial/7-schemas-and-client-libraries.md'
  - API Guide:
     - 'Requests': 'api-guide/requests.md'
     - 'Responses': 'api-guide/responses.md'

requirements/requirements-optionals.txt

@@ -2,3 +2,4 @@
 markdown==2.6.4
 django-guardian==1.4.3
 django-filter==0.13.0
+coreapi==1.21.1

rest_framework/compat.py

@@ -156,6 +156,16 @@ def value_from_object(field, obj):
     crispy_forms = None
 
 
+# coreapi is optional (Note that uritemplate is a dependancy of coreapi)
+try:
+    import coreapi
+    import uritemplate
+except (ImportError, SyntaxError):
+    # SyntaxError is possible under python 3.2
+    coreapi = None
+    uritemplate = None
+
+
 # Django-guardian is optional. Import only if guardian is in INSTALLED_APPS
 # Fixes (#1712). We keep the try/except for the test suite.
 guardian = None

rest_framework/renderers.py

@@ -22,7 +22,8 @@
 
 from rest_framework import VERSION, exceptions, serializers, status
 from rest_framework.compat import (
-    INDENT_SEPARATORS, LONG_SEPARATORS, SHORT_SEPARATORS, template_render
+    INDENT_SEPARATORS, LONG_SEPARATORS, SHORT_SEPARATORS, coreapi,
+    template_render
 )
 from rest_framework.exceptions import ParseError
 from rest_framework.request import is_form_media_type, override_method
@@ -790,3 +791,17 @@ def render(self, data, accepted_media_type=None, renderer_context=None):
                     "test case." % key
                 )
         return encode_multipart(self.BOUNDARY, data)
+
+
+class CoreJSONRenderer(BaseRenderer):
+    media_type = 'application/vnd.coreapi+json'
+    charset = None
+    format = 'corejson'
+
+    def __init__(self):
+        assert coreapi, 'Using CoreJSONRenderer, but `coreapi` is not installed.'
+
+    def render(self, data, media_type=None, renderer_context=None):
+        indent = bool(renderer_context.get('indent', 0))
+        codec = coreapi.codecs.CoreJSONCodec()
+        return codec.dump(data, indent=indent)

rest_framework/routers.py

@@ -22,9 +22,12 @@
 from django.core.exceptions import ImproperlyConfigured
 from django.core.urlresolvers import NoReverseMatch
 
-from rest_framework import views
+from rest_framework import exceptions, renderers, views
+from rest_framework.compat import coreapi
 from rest_framework.response import Response
 from rest_framework.reverse import reverse
+from rest_framework.schemas import SchemaGenerator
+from rest_framework.settings import api_settings
 from rest_framework.urlpatterns import format_suffix_patterns
 
 Route = namedtuple('Route', ['url', 'mapping', 'name', 'initkwargs'])
@@ -252,6 +255,7 @@ def get_urls(self):
                     lookup=lookup,
                     trailing_slash=self.trailing_slash
                 )
+
                 view = viewset.as_view(mapping, **route.initkwargs)
                 name = route.name.format(basename=basename)
                 ret.append(url(regex, view, name=name))
@@ -268,7 +272,11 @@ class DefaultRouter(SimpleRouter):
     include_format_suffixes = True
     root_view_name = 'api-root'
 
-    def get_api_root_view(self):
+    def __init__(self, *args, **kwargs):
+        self.schema_title = kwargs.pop('schema_title', None)
+        super(DefaultRouter, self).__init__(*args, **kwargs)
+
+    def get_api_root_view(self, schema_urls=None):
         """
         Return a view to use as the API root.
         """
@@ -277,10 +285,24 @@ def get_api_root_view(self):
         for prefix, viewset, basename in self.registry:
             api_root_dict[prefix] = list_name.format(basename=basename)
 
+        view_renderers = list(api_settings.DEFAULT_RENDERER_CLASSES)
+
+        if schema_urls and self.schema_title:
+            assert coreapi, '`coreapi` must be installed for schema support.'
+            view_renderers += [renderers.CoreJSONRenderer]
+            schema_generator = SchemaGenerator(patterns=schema_urls)
+
         class APIRoot(views.APIView):
             _ignore_model_permissions = True
+            renderer_classes = view_renderers
 
             def get(self, request, *args, **kwargs):
+                if request.accepted_renderer.format == 'corejson':
+                    schema = schema_generator.get_schema(request)
+                    if schema is None:
+                        raise exceptions.PermissionDenied()
+                    return Response(schema)
+
                 ret = OrderedDict()
                 namespace = request.resolver_match.namespace
                 for key, url_name in api_root_dict.items():
@@ -307,15 +329,13 @@ def get_urls(self):
         Generate the list of URL patterns, including a default root view
         for the API, and appending `.json` style format suffixes.
         """
-        urls = []
+        urls = super(DefaultRouter, self).get_urls()
 
         if self.include_root_view:
-            root_url = url(r'^$', self.get_api_root_view(), name=self.root_view_name)
+            view = self.get_api_root_view(schema_urls=urls)
+            root_url = url(r'^$', view, name=self.root_view_name)
             urls.append(root_url)
 
-        default_urls = super(DefaultRouter, self).get_urls()
-        urls.extend(default_urls)
-
         if self.include_format_suffixes:
             urls = format_suffix_patterns(urls)