Remove Core API mentions from docs (#8780)

* remove coreapi generator mentions & hidden docs * remove coreapi doc & redirect broken links to github snapshot
2024-11-22 01:26:53 +03:00 · 2022-11-28 14:41:08 +01:00 · 2022-11-28 14:41:08 +01:00 · f0095b4de2
commit f0095b4de2
parent 5435b2c9f0
11 changed files with 4 additions and 1857 deletions
--- a/docs/api-guide/filtering.md
+++ b/docs/api-guide/filtering.md
@ -335,15 +335,6 @@ Generic filters may also present an interface in the browsable API. To do so you
 The method should return a rendered HTML string.
 ## Filtering & schemas
 You can also make the filter controls available to the schema autogeneration
 that REST framework provides, by implementing a `get_schema_fields()` method. This method should have the following signature:
 `get_schema_fields(self, view)`
 The method should return a list of `coreapi.Field` instances.
 # Third party packages
 The following third party packages provide additional filter implementations.
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@ -264,15 +264,6 @@ API responses for list endpoints will now include a `Link` header, instead of in
 *A custom pagination style, using the 'Link' header'*
 ## Pagination & schemas
 You can also make the pagination controls available to the schema autogeneration
 that REST framework provides, by implementing a `get_schema_fields()` method. This method should have the following signature:
 `get_schema_fields(self, view)`
 The method should return a list of `coreapi.Field` instances.
 ---
 # HTML pagination controls
--- a/docs/community/3.10-announcement.md
+++ b/docs/community/3.10-announcement.md
@ -142,6 +142,6 @@ continued development by **[signing up for a paid plan][funding]**.
 *Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).*
-[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md
+[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/3.14.0/docs/coreapi/index.md
 [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
 [funding]: funding.md
--- a/docs/community/3.4-announcement.md
+++ b/docs/community/3.4-announcement.md
@ -187,7 +187,7 @@ The full set of itemized release notes [are available here][release-notes].
 [api-blueprint]: https://apiblueprint.org/
 [tut-7]: ../tutorial/7-schemas-and-client-libraries/
 [schema-generation]: ../api-guide/schemas/
-[api-clients]: ../topics/api-clients.md
+[api-clients]: https://github.com/encode/django-rest-framework/blob/3.14.0/docs/topics/api-clients.md
 [milestone]: https://github.com/encode/django-rest-framework/milestone/35
 [release-notes]: release-notes#34
 [metadata]: ../api-guide/metadata/#custom-metadata-classes
--- a/docs/community/3.6-announcement.md
+++ b/docs/community/3.6-announcement.md
@ -195,5 +195,5 @@ on realtime support, for the 3.7 release.
 [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
 [funding]: funding.md
 [api-docs]: ../topics/documenting-your-api.md
-[js-docs]: ../topics/api-clients.md#javascript-client-library
+[js-docs]: https://github.com/encode/django-rest-framework/blob/3.14.0/docs/topics/api-clients.md#javascript-client-library
-[py-docs]: ../topics/api-clients.md#python-client-library
+[py-docs]: https://github.com/encode/django-rest-framework/blob/3.14.0/docs/topics/api-clients.md#python-client-library
--- a/docs/coreapi/7-schemas-and-client-libraries.md
+++ b/docs/coreapi/7-schemas-and-client-libraries.md
@ -1,242 +0,0 @@
 # Tutorial 7: Schemas & client libraries
 ----
 **DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details.
 If you are looking for information regarding schemas, you might want to look at these updated resources:
 1. [Schema](../api-guide/schemas.md)
 2. [Documenting your API](../topics/documenting-your-api.md)
 ----
 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, and `pyyaml` to render the schema into the commonly used
 YAML-based OpenAPI format.
    $ pip install coreapi pyyaml
 We can now include a schema for our API, by including an autogenerated schema
 view in our URL configuration.
 ```python
 from rest_framework.schemas import get_schema_view
 schema_view = get_schema_view(title='Pastebin API')
 urlpatterns = [
    path('schema/', schema_view),
    ...
 ]
 ```
 If you visit the `/schema/` 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/schema/ Accept:application/coreapi+json
    HTTP/1.0 200 OK
    Allow: GET, HEAD, OPTIONS
    Content-Type: application/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.
 The command line client is available as the `coreapi-cli` package:
    $ pip install coreapi-cli
 Now check that it is available on the command line...
    $ coreapi
    Usage: coreapi [OPTIONS] COMMAND [ARGS]...
      Command line client for interacting with CoreAPI services.
      Visit https://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/schema/
    <Pastebin API "http://127.0.0.1:8000/schema/">
        snippets: {
            highlight(id)
            list()
            read(id)
        }
        users: {
            list()
            read(id)
        }
 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/",
            "id": 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 id=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/schema/">
        snippets: {
            create(code, [title], [linenos], [language], [style])
            delete(id)
            highlight(id)
            list()
            partial_update(id, [title], [code], [linenos], [language], [style])
            read(id)
            update(id, code, [title], [linenos], [language], [style])
        }
        users: {
            list()
            read(id)
        }
 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 delete --param id=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]: https://www.coreapi.org/
 [corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding
 [openapi]: https://openapis.org/
 [repo]: https://github.com/encode/rest-framework-tutorial
 [sandbox]: https://restframework.herokuapp.com/
 [github]: https://github.com/encode/django-rest-framework
 [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
 [twitter]: https://twitter.com/_tomchristie
--- a/docs/coreapi/from-documenting-your-api.md
+++ b/docs/coreapi/from-documenting-your-api.md
@ -1,182 +0,0 @@
 ## Built-in API documentation
 ----
 **DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details.
 If you are looking for information regarding schemas, you might want to look at these updated resources:
 1. [Schema](../api-guide/schemas.md)
 2. [Documenting your API](../topics/documenting-your-api.md)
 ----
 The built-in API documentation includes:
 * Documentation of API endpoints.
 * Automatically generated code samples for each of the available API client libraries.
 * Support for API interaction.
 ### Installation
 The `coreapi` library is required as a dependency for the API docs. Make sure
 to install the latest version. The `Pygments` and `Markdown` libraries
 are optional but recommended.
 To install the API documentation, you'll need to include it in your project's URLconf:
    from rest_framework.documentation import include_docs_urls
    urlpatterns = [
        ...
        path('docs/', include_docs_urls(title='My API title'))
    ]
 This will include two different views:
  * `/docs/` - The documentation page itself.
  * `/docs/schema.js` - A JavaScript resource that exposes the API schema.
 ---
 **Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas.
 This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`.
 To be compatible with this behavior, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case.
 You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`:
    from rest_framework.documentation import include_docs_urls
    urlpatterns = [
        ...
        # Generate schema with valid `request` instance:
        path('docs/', include_docs_urls(title='My API title', public=False))
    ]
 ---
 ### Documenting your views
 You can document your views by including docstrings that describe each of the available actions.
 For example:
    class UserList(generics.ListAPIView):
        """
        Return a list of all the existing users.
        """
 If a view supports multiple methods, you should split your documentation using `method:` style delimiters.
    class UserList(generics.ListCreateAPIView):
        """
        get:
        Return a list of all the existing users.
        post:
        Create a new user instance.
        """
 When using viewsets, you should use the relevant action names as delimiters.
    class UserViewSet(viewsets.ModelViewSet):
        """
        retrieve:
        Return the given user.
        list:
        Return a list of all the existing users.
        create:
        Create a new user instance.
        """
 Custom actions on viewsets can also be documented in a similar way using the method names
 as delimiters or by attaching the documentation to action mapping methods.
    class UserViewSet(viewsets.ModelViewset):
        ...
        @action(detail=False, methods=['get', 'post'])
        def some_action(self, request, *args, **kwargs):
            """
            get:
            A description of the get method on the custom action.
            post:
            A description of the post method on the custom action.
            """
        @some_action.mapping.put
        def put_some_action():
            """
            A description of the put method on the custom action.
            """
 ### `documentation` API Reference
 The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`.
 `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.)
 #### `include_docs_urls`
 * `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
 * `description`: Default `None`. May be used to provide a description for the schema definition.
 * `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
 * `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views.
 * `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
 * `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
 * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
 * `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`.
 #### `get_docs_view`
 * `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
 * `description`: Default `None`. May be used to provide a description for the schema definition.
 * `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
 * `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
 * `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
 * `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
 * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`.
 * `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats.
 #### `get_schemajs_view`
 * `title`: Default `None`. May be used to provide a descriptive title for the schema definition.
 * `description`: Default `None`. May be used to provide a description for the schema definition.
 * `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema.
 * `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views.
 * `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used.
 * `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`.
 * `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`.
 * `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`.
 ### Customising code samples
 The built-in API documentation includes automatically generated code samples for
 each of the available API client libraries.
 You may customise these samples by subclassing `DocumentationRenderer`, setting
 `languages` to the list of languages you wish to support:
    from rest_framework.renderers import DocumentationRenderer
    class CustomRenderer(DocumentationRenderer):
        languages = ['ruby', 'go']
 For each language you need to provide an `intro` template, detailing installation instructions and such,
 plus a generic template for making API requests, that can be filled with individual request details.
 See the [templates for the bundled languages][client-library-templates] for examples.
 ---
 [client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs
--- a/docs/coreapi/index.md
+++ b/docs/coreapi/index.md
@ -1,29 +0,0 @@
 # Legacy CoreAPI Schemas Docs
 Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10.
 See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details.
 ----
 You can continue to use CoreAPI schemas by setting the appropriate default schema class:
 ```python
 # In settings.py
 REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
 }
 ```
 Under-the-hood, any subclass of `coreapi.AutoSchema` here will trigger use of the old CoreAPI schemas.
 **Otherwise** you will automatically be opted-in to the new OpenAPI schemas.
 All CoreAPI related code will be removed in Django REST Framework v3.12. Switch to OpenAPI schemas by then.
 ----
 For reference this folder contains the old CoreAPI related documentation:
 * [Tutorial 7: Schemas & client libraries](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//7-schemas-and-client-libraries.md).
 * [Excerpts from _Documenting your API_ topic page](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//from-documenting-your-api.md).
 * [`rest_framework.schemas` API Reference](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//schemas.md).
--- a/docs/coreapi/schemas.md
+++ b/docs/coreapi/schemas.md
@ -1,854 +0,0 @@
 source: schemas.py
 # Schemas
 ----
 **DEPRECATION NOTICE:** Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation as of Django REST Framework v3.10. See the [Version 3.10 Release Announcement](../community/3.10-announcement.md) for more details.
 You are probably looking for [this page](../api-guide/schemas.md) if you want latest information regarding schemas.
 ----
 > A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support.
 >
 > &mdash; Heroku, [JSON Schema for the Heroku Platform API][cite]
 API schemas are a useful tool that allow for a range of use cases, including
 generating reference documentation, or driving dynamic client libraries that
 can interact with your API.
 ## Install Core API & PyYAML
 You'll need to install the `coreapi` package in order to add schema support
 for REST framework. You probably also want to install `pyyaml`, so that you
 can render the schema into the commonly used YAML-based OpenAPI format.
    pip install coreapi pyyaml
 ## Quickstart
 There are two different ways you can serve a schema description for your API.
 ### Generating a schema with the `generateschema` management command
 To generate a static API schema, use the `generateschema` management command.
 ```shell
 $ python manage.py generateschema > schema.yml
 ```
 Once you've generated a schema in this way you can annotate it with any
 additional information that cannot be automatically inferred by the schema
 generator.
 You might want to check your API schema into version control and update it
 with each new release, or serve the API schema from your site's static media.
 ### Adding a view with `get_schema_view`
 To add a dynamically generated schema view to your API, use `get_schema_view`.
 ```python
 from rest_framework.schemas import get_schema_view
 from django.urls import path
 schema_view = get_schema_view(title="Example API")
 urlpatterns = [
    path('schema', schema_view),
    ...
 ]
 ```
 See below [for more details](#the-get_schema_view-shortcut) on customizing a
 dynamically generated schema view.
 ## Internal schema representation
 REST framework uses [Core API][coreapi] in order to model schema information in
 a format-independent representation. This information can then be rendered
 into various different schema formats, or used to generate API documentation.
 When using Core API, a schema is represented as a `Document` which is the
 top-level container object for information about the API. Available API
 interactions are represented using `Link` objects. Each link includes a URL,
 HTTP method, and may include a list of `Field` instances, which describe any
 parameters that may be accepted by the API endpoint. The `Link` and `Field`
 instances may also include descriptions, that allow an API schema to be
 rendered into user documentation.
 Here's an example of an API description that includes a single `search`
 endpoint:
    coreapi.Document(
        title='Flight Search API',
        url='https://api.example.org/',
        content={
            'search': coreapi.Link(
                url='/search/',
                action='get',
                fields=[
                    coreapi.Field(
                        name='from',
                        required=True,
                        location='query',
                        description='City name or airport code.'
                    ),
                    coreapi.Field(
                        name='to',
                        required=True,
                        location='query',
                        description='City name or airport code.'
                    ),
                    coreapi.Field(
                        name='date',
                        required=True,
                        location='query',
                        description='Flight date in "YYYY-MM-DD" format.'
                    )
                ],
                description='Return flight availability and prices.'
            )
        }
    )
 ## Schema output formats
 In order to be presented in an HTTP response, the internal representation
 has to be rendered into the actual bytes that are used in the response.
 REST framework includes a few different renderers that you can use for
 encoding the API schema.
 * `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format.
 * `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api].
 * `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for
 use with the `coreapi` client library.
 [Core JSON][corejson] is designed as a canonical format for use with Core API.
 REST framework includes a renderer class for handling this media type, which
 is available as `renderers.CoreJSONRenderer`.
 ## Schemas vs Hypermedia
 It's worth pointing out here that Core API can also be used to model hypermedia
 responses, which present an alternative interaction style to API schemas.
 With an API schema, the entire available interface is presented up-front
 as a single endpoint. Responses to individual API endpoints are then typically
 presented as plain data, without any further interactions contained in each
 response.
 With Hypermedia, the client is instead presented with a document containing
 both data and available interactions. Each interaction results in a new
 document, detailing both the current state and the available interactions.
 Further information and support on building Hypermedia APIs with REST framework
 is planned for a future version.
 ---
 # Creating a schema
 REST framework includes functionality for auto-generating a schema,
 or allows you to specify one explicitly.
 ## Manual Schema Specification
 To manually specify a schema you create a Core API `Document`, similar to the
 example above.
    schema = coreapi.Document(
        title='Flight Search API',
        content={
            ...
        }
    )
 ## Automatic Schema Generation
 Automatic schema generation is provided by the `SchemaGenerator` class.
 `SchemaGenerator` processes a list of routed URL patterns and compiles the
 appropriately structured Core API Document.
 Basic usage is just to provide the title for your schema and call
 `get_schema()`:
    generator = schemas.SchemaGenerator(title='Flight Search API')
    schema = generator.get_schema()
 ## Per-View Schema Customisation
 By default, view introspection is performed by an `AutoSchema` instance
 accessible via the `schema` attribute on `APIView`. This provides the
 appropriate Core API `Link` object for the view, request method and path:
    auto_schema = view.schema
    coreapi_link = auto_schema.get_link(...)
 (In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for
 each view, allowed method and path.)
 ---
 **Note**: For basic `APIView` subclasses, default introspection is essentially
 limited to the URL kwarg path parameters. For `GenericAPIView`
 subclasses, which includes all the provided class based views, `AutoSchema` will
 attempt to introspect serializer, pagination and filter fields, as well as
 provide richer path field descriptions. (The key hooks here are the relevant
 `GenericAPIView` attributes and methods: `get_serializer`, `pagination_class`,
 `filter_backends` and so on.)
 ---
 To customise the `Link` generation you may:
 * Instantiate `AutoSchema` on your view with the `manual_fields` kwarg:
        from rest_framework.views import APIView
        from rest_framework.schemas import AutoSchema
        class CustomView(APIView):
            ...
            schema = AutoSchema(
                manual_fields=[
                    coreapi.Field("extra_field", ...),
                ]
            )
    This allows extension for the most common case without subclassing.
 * Provide an `AutoSchema` subclass with more complex customisation:
        from rest_framework.views import APIView
        from rest_framework.schemas import AutoSchema
        class CustomSchema(AutoSchema):
            def get_link(...):
                # Implement custom introspection here (or in other sub-methods)
        class CustomView(APIView):
            ...
            schema = CustomSchema()
    This provides complete control over view introspection.
 * Instantiate `ManualSchema` on your view, providing the Core API `Fields` for
  the view explicitly:
        from rest_framework.views import APIView
        from rest_framework.schemas import ManualSchema
        class CustomView(APIView):
            ...
            schema = ManualSchema(fields=[
                coreapi.Field(
                    "first_field",
                    required=True,
                    location="path",
                    schema=coreschema.String()
                ),
                coreapi.Field(
                    "second_field",
                    required=True,
                    location="path",
                    schema=coreschema.String()
                ),
            ])
    This allows manually specifying the schema for some views whilst maintaining
    automatic generation elsewhere.
 You may disable schema generation for a view by setting `schema` to `None`:
        class CustomView(APIView):
            ...
            schema = None  # Will not appear in schema
 This also applies to extra actions for `ViewSet`s:
        class CustomViewSet(viewsets.ModelViewSet):
            @action(detail=True, schema=None)
            def extra_action(self, request, pk=None):
                ...
 ---
 **Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and
 `ManualSchema` descriptors see the [API Reference below](#api-reference).
 ---
 # Adding a schema view
 There are a few different ways to add a schema view to your API, depending on
 exactly what you need.
 ## The get_schema_view shortcut
 The simplest way to include a schema in your project is to use the
 `get_schema_view()` function.
    from rest_framework.schemas import get_schema_view
    schema_view = get_schema_view(title="Server Monitoring API")
    urlpatterns = [
        path('', schema_view),
        ...
    ]
 Once the view has been added, you'll be able to make API requests to retrieve
 the auto-generated schema definition.
    $ http http://127.0.0.1:8000/ Accept:application/coreapi+json
    HTTP/1.0 200 OK
    Allow: GET, HEAD, OPTIONS
    Content-Type: application/vnd.coreapi+json
    {
        "_meta": {
            "title": "Server Monitoring API"
        },
        "_type": "document",
        ...
    }
 The arguments to `get_schema_view()` are:
 #### `title`
 May be used to provide a descriptive title for the schema definition.
 #### `url`
 May be used to pass a canonical URL for the schema.
    schema_view = get_schema_view(
        title='Server Monitoring API',
        url='https://www.example.org/api/'
    )
 #### `urlconf`
 A string representing the import path to the URL conf that you want
 to generate an API schema for. This defaults to the value of Django's
 ROOT_URLCONF setting.
    schema_view = get_schema_view(
        title='Server Monitoring API',
        url='https://www.example.org/api/',
        urlconf='myproject.urls'
    )
 #### `renderer_classes`
 May be used to pass the set of renderer classes that can be used to render the API root endpoint.
    from rest_framework.schemas import get_schema_view
    from rest_framework.renderers import JSONOpenAPIRenderer
    schema_view = get_schema_view(
        title='Server Monitoring API',
        url='https://www.example.org/api/',
        renderer_classes=[JSONOpenAPIRenderer]
    )
 #### `patterns`
 List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls
 to be exposed in the schema:
    schema_url_patterns = [
        path('api/', include('myproject.api.urls')),
    ]
    schema_view = get_schema_view(
        title='Server Monitoring API',
        url='https://www.example.org/api/',
        patterns=schema_url_patterns,
    )
 #### `generator_class`
 May be used to specify a `SchemaGenerator` subclass to be passed to the
 `SchemaView`.
 #### `authentication_classes`
 May be used to specify the list of authentication classes that will apply to the schema endpoint.
 Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES`
 #### `permission_classes`
 May be used to specify the list of permission classes that will apply to the schema endpoint.
 Defaults to `settings.DEFAULT_PERMISSION_CLASSES`
 ## Using an explicit schema view
 If you need a little more control than the `get_schema_view()` shortcut gives you,
 then you can use the `SchemaGenerator` class directly to auto-generate the
 `Document` instance, and to return that from a view.
 This option gives you the flexibility of setting up the schema endpoint
 with whatever behavior you want. For example, you can apply different
 permission, throttling, or authentication policies to the schema endpoint.
 Here's an example of using `SchemaGenerator` together with a view to
 return the schema.
 **views.py:**
    from rest_framework.decorators import api_view, renderer_classes
    from rest_framework import renderers, response, schemas
    generator = schemas.SchemaGenerator(title='Bookings API')
    @api_view()
    @renderer_classes([renderers.OpenAPIRenderer])
    def schema_view(request):
        schema = generator.get_schema(request)
        return response.Response(schema)
 **urls.py:**
    urlpatterns = [
        path('', schema_view),
        ...
    ]
 You can also serve different schemas to different users, depending on the
 permissions they have available. This approach can be used to ensure that
 unauthenticated requests are presented with a different schema to
 authenticated requests, or to ensure that different parts of the API are
 made visible to different users depending on their role.
 In order to present a schema with endpoints filtered by user permissions,
 you need to pass the `request` argument to the `get_schema()` method, like so:
    @api_view()
    @renderer_classes([renderers.OpenAPIRenderer])
    def schema_view(request):
        generator = schemas.SchemaGenerator(title='Bookings API')
        return response.Response(generator.get_schema(request=request))
 ## Explicit schema definition
 An alternative to the auto-generated approach is to specify the API schema
 explicitly, by declaring a `Document` object in your codebase. Doing so is a
 little more work, but ensures that you have full control over the schema
 representation.
    import coreapi
    from rest_framework.decorators import api_view, renderer_classes
    from rest_framework import renderers, response
    schema = coreapi.Document(
        title='Bookings API',
        content={
            ...
        }
    )
    @api_view()
    @renderer_classes([renderers.OpenAPIRenderer])
    def schema_view(request):
        return response.Response(schema)
 ---
 # Schemas as documentation
 One common usage of API schemas is to use them to build documentation pages.
 The schema generation in REST framework uses docstrings to automatically
 populate descriptions in the schema document.
 These descriptions will be based on:
 * The corresponding method docstring if one exists.
 * A named section within the class docstring, which can be either single line or multi-line.
 * The class docstring.
 ## Examples
 An `APIView`, with an explicit method docstring.
    class ListUsernames(APIView):
        def get(self, request):
            """
            Return a list of all user names in the system.
            """
            usernames = [user.username for user in User.objects.all()]
            return Response(usernames)
 A `ViewSet`, with an explicit action docstring.
    class ListUsernames(ViewSet):
        def list(self, request):
            """
            Return a list of all user names in the system.
            """
            usernames = [user.username for user in User.objects.all()]
            return Response(usernames)
 A generic view with sections in the class docstring, using single-line style.
    class UserList(generics.ListCreateAPIView):
        """
        get: List all the users.
        post: Create a new user.
        """
        queryset = User.objects.all()
        serializer_class = UserSerializer
        permission_classes = [IsAdminUser]
 A generic viewset with sections in the class docstring, using multi-line style.
    class UserViewSet(viewsets.ModelViewSet):
        """
        API endpoint that allows users to be viewed or edited.
        retrieve:
        Return a user instance.
        list:
        Return all users, ordered by most recently joined.
        """
        queryset = User.objects.all().order_by('-date_joined')
        serializer_class = UserSerializer
 ---
 # API Reference
 ## SchemaGenerator
 A class that walks a list of routed URL patterns, requests the schema for each view,
 and collates the resulting CoreAPI Document.
 Typically you'll instantiate `SchemaGenerator` with a single argument, like so:
    generator = SchemaGenerator(title='Stock Prices API')
 Arguments:
 * `title` **required** - The name of the API.
 * `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix.
 * `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf.
 * `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`.
 ### get_schema(self, request)
 Returns a `coreapi.Document` instance that represents the API schema.
    @api_view
    @renderer_classes([renderers.OpenAPIRenderer])
    def schema_view(request):
        generator = schemas.SchemaGenerator(title='Bookings API')
        return Response(generator.get_schema())
 The `request` argument is optional, and may be used if you want to apply per-user
 permissions to the resulting schema generation.
 ### get_links(self, request)
 Return a nested dictionary containing all the links that should be included in the API schema.
 This is a good point to override if you want to modify the resulting structure of the generated schema,
 as you can build a new dictionary with a different layout.
 ## AutoSchema
 A class that deals with introspection of individual views for schema generation.
 `AutoSchema` is attached to `APIView` via the `schema` attribute.
 The `AutoSchema` constructor takes a single keyword argument `manual_fields`.
 **`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to
 the generated fields. Generated fields with a matching `name` will be overwritten.
    class CustomView(APIView):
        schema = AutoSchema(manual_fields=[
            coreapi.Field(
                "my_extra_field",
                required=True,
                location="path",
                schema=coreschema.String()
            ),
        ])
 For more advanced customisation subclass `AutoSchema` to customise schema generation.
    class CustomViewSchema(AutoSchema):
        """
        Overrides `get_link()` to provide Custom Behavior X
        """
        def get_link(self, path, method, base_url):
            link = super().get_link(path, method, base_url)
            # Do something to customize link here...
            return link
    class MyView(APIView):
      schema = CustomViewSchema()
 The following methods are available to override.
 ### get_link(self, path, method, base_url)
 Returns a `coreapi.Link` instance corresponding to the given view.
 This is the main entry point.
 You can override this if you need to provide custom behaviors for particular views.
 ### get_description(self, path, method)
 Returns a string to use as the link description. By default this is based on the
 view docstring as described in the "Schemas as Documentation" section above.
 ### get_encoding(self, path, method)
 Returns a string to indicate the encoding for any request body, when interacting
 with the given view. Eg. `'application/json'`. May return a blank string for views
 that do not expect a request body.
 ### get_path_fields(self, path, method):
 Return a list of `coreapi.Field()` instances. One for each path parameter in the URL.
 ### get_serializer_fields(self, path, method)
 Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view.
 ### get_pagination_fields(self, path, method)
 Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view.
 ### get_filter_fields(self, path, method)
 Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view.
 ### get_manual_fields(self, path, method)
 Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor.
 May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this:
 ```python
 def get_manual_fields(self, path, method):
    """Example adding per-method fields."""
    extra_fields = []
    if method == 'GET':
        extra_fields = ...  # list of extra fields for GET
    if method == 'POST':
        extra_fields = ...  # list of extra fields for POST
    manual_fields = super().get_manual_fields(path, method)
    return manual_fields + extra_fields
 ```
 ### update_fields(fields, update_with)
 Utility `staticmethod`. Encapsulates logic to add or replace fields from a list
 by `Field.name`. May be overridden to adjust replacement criteria.
 ## ManualSchema
 Allows manually providing a list of `coreapi.Field` instances for the schema,
 plus an optional description.
    class MyView(APIView):
      schema = ManualSchema(fields=[
            coreapi.Field(
                "first_field",
                required=True,
                location="path",
                schema=coreschema.String()
            ),
            coreapi.Field(
                "second_field",
                required=True,
                location="path",
                schema=coreschema.String()
            ),
        ]
      )
 The `ManualSchema` constructor takes two arguments:
 **`fields`**: A list of `coreapi.Field` instances. Required.
 **`description`**: A string description. Optional.
 **`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional.
 ---
 ## Core API
 This documentation gives a brief overview of the components within the `coreapi`
 package that are used to represent an API schema.
 Note that these classes are imported from the `coreapi` package, rather than
 from the `rest_framework` package.
 ### Document
 Represents a container for the API schema.
 #### `title`
 A name for the API.
 #### `url`
 A canonical URL for the API.
 #### `content`
 A dictionary, containing the `Link` objects that the schema contains.
 In order to provide more structure to the schema, the `content` dictionary
 may be nested, typically to a second level. For example:
    content={
        "bookings": {
            "list": Link(...),
            "create": Link(...),
            ...
        },
        "venues": {
            "list": Link(...),
            ...
        },
        ...
    }
 ### Link
 Represents an individual API endpoint.
 #### `url`
 The URL of the endpoint. May be a URI template, such as `/users/{username}/`.
 #### `action`
 The HTTP method associated with the endpoint. Note that URLs that support
 more than one HTTP method, should correspond to a single `Link` for each.
 #### `fields`
 A list of `Field` instances, describing the available parameters on the input.
 #### `description`
 A short description of the meaning and intended usage of the endpoint.
 ### Field
 Represents a single input parameter on a given API endpoint.
 #### `name`
 A descriptive name for the input.
 #### `required`
 A boolean, indicated if the client is required to included a value, or if
 the parameter can be omitted.
 #### `location`
 Determines how the information is encoded into the request. Should be one of
 the following strings:
 **"path"**
 Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`.
 These fields will normally correspond with [named arguments in the project URL conf][named-arguments].
 **"query"**
 Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests.
 These fields will normally correspond with pagination and filtering controls on a view.
 **"form"**
 Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link.
 These fields will normally correspond with serializer fields on a view.
 **"body"**
 Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields.
 These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views.
 #### `encoding`
 **"application/json"**
 JSON encoded request content. Corresponds to views using `JSONParser`.
 Valid only if either one or more `location="form"` fields, or a single
 `location="body"` field is included on the `Link`.
 **"multipart/form-data"**
 Multipart encoded request content. Corresponds to views using `MultiPartParser`.
 Valid only if one or more `location="form"` fields is included on the `Link`.
 **"application/x-www-form-urlencoded"**
 URL encoded request content. Corresponds to views using `FormParser`. Valid
 only if one or more `location="form"` fields is included on the `Link`.
 **"application/octet-stream"**
 Binary upload request content. Corresponds to views using `FileUploadParser`.
 Valid only if a `location="body"` field is included on the `Link`.
 #### `description`
 A short description of the meaning and intended usage of the input field.
 ---
 # Third party packages
 ## drf-yasg - Yet Another Swagger Generator
 [drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas,
 named models, response bodies, enum/pattern/min/max validators, form parameters, etc.
 ## drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework
 [drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility,
 customizability and client generation. It's usage patterns are very similar to [drf-yasg][drf-yasg].
 [cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api
 [coreapi]: https://www.coreapi.org/
 [corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding
 [drf-yasg]: https://github.com/axnsan12/drf-yasg/
 [drf-spectacular]: https://github.com/tfranzel/drf-spectacular/
 [open-api]: https://openapis.org/
 [json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html
 [api-blueprint]: https://apiblueprint.org/
 [static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/
 [named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups
--- a/docs/topics/api-clients.md
+++ b/docs/topics/api-clients.md
@ -1,527 +0,0 @@
 # API Clients
 An API client handles the underlying details of how network requests are made
 and how responses are decoded. They present the developer with an application
 interface to work against, rather than working directly with the network interface.
 The API clients documented here are not restricted to APIs built with Django REST framework.
 They can be used with any API that exposes a supported schema format.
 For example, [the Heroku platform API][heroku-api] exposes a schema in the JSON
 Hyperschema format. As a result, the Core API command line client and Python
 client library can be [used to interact with the Heroku API][heroku-example].
 ## Client-side Core API
 [Core API][core-api] is a document specification that can be used to describe APIs. It can
 be used either server-side, as is done with REST framework's [schema generation][schema-generation],
 or used client-side, as described here.
 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.
 Using a dynamically driven client has a number of advantages over interacting
 with an API by building HTTP requests directly.
 #### More meaningful interaction
 API interactions are presented in a more meaningful way. You're working at
 the application interface layer, rather than the network interface layer.
 #### Resilience & evolvability
 The client determines what endpoints are available, what parameters exist
 against each particular endpoint, and how HTTP requests are formed.
 This also allows for a degree of API evolvability. URLs can be modified
 without breaking existing clients, or more efficient encodings can be used
 on-the-wire, with clients transparently upgrading.
 #### Self-descriptive APIs
 A dynamically driven client is able to present documentation on the API to the
 end user. This documentation allows the user to discover the available endpoints
 and parameters, and better understand the API they are working with.
 Because this documentation is driven by the API schema it will always be fully
 up to date with the most recently deployed version of the service.
 ---
 # Command line client
 The command line client allows you to inspect and interact with any API that
 exposes a supported schema format.
 ## Getting started
 To install the Core API command line client, use `pip`.
 Note that the command-line client is a separate package to the
 python client library. Make sure to install `coreapi-cli`.
    $ pip install coreapi-cli
 To start inspecting and interacting with an API the schema must first be loaded
 from the network.
    $ coreapi get http://api.example.org/
    <Pastebin API "http://127.0.0.1:8000/">
    snippets: {
        create(code, [title], [linenos], [language], [style])
        destroy(pk)
        highlight(pk)
        list([page])
        partial_update(pk, [title], [code], [linenos], [language], [style])
        retrieve(pk)
        update(pk, code, [title], [linenos], [language], [style])
    }
    users: {
        list([page])
        retrieve(pk)
    }
 This will then load the schema, displaying the resulting `Document`. This
 `Document` includes all the available interactions that may be made against the API.
 To interact with the API, use the `action` command. This command requires a list
 of keys that are used to index into the link.
    $ coreapi action users list
    [
        {
            "url": "http://127.0.0.1:8000/users/2/",
            "id": 2,
            "username": "aziz",
            "snippets": []
        },
        ...
    ]
 To inspect the underlying HTTP request and response, use the `--debug` flag.
    $ coreapi action users list --debug
    > GET /users/ HTTP/1.1
    > Accept: application/vnd.coreapi+json, */*
    > Authorization: Basic bWF4Om1heA==
    > Host: 127.0.0.1
    > User-Agent: coreapi
    < 200 OK
    < Allow: GET, HEAD, OPTIONS
    < Content-Type: application/json
    < Date: Thu, 30 Jun 2016 10:51:46 GMT
    < Server: WSGIServer/0.1 Python/2.7.10
    < Vary: Accept, Cookie
    <
    < [{"url":"http://127.0.0.1/users/2/","id":2,"username":"aziz","snippets":[]},{"url":"http://127.0.0.1/users/3/","id":3,"username":"amy","snippets":["http://127.0.0.1/snippets/3/"]},{"url":"http://127.0.0.1/users/4/","id":4,"username":"max","snippets":["http://127.0.0.1/snippets/4/","http://127.0.0.1/snippets/5/","http://127.0.0.1/snippets/6/","http://127.0.0.1/snippets/7/"]},{"url":"http://127.0.0.1/users/5/","id":5,"username":"jose","snippets":[]},{"url":"http://127.0.0.1/users/6/","id":6,"username":"admin","snippets":["http://127.0.0.1/snippets/1/","http://127.0.0.1/snippets/2/"]}]
    [
        ...
    ]
 Some actions may include optional or required parameters.
    $ coreapi action users create --param username=example
 When using `--param`, the type of the input will be determined automatically.
 If you want to be more explicit about the parameter type then use `--data` for
 any null, numeric, boolean, list, or object inputs, and use `--string` for string inputs.
    $ coreapi action users edit --string username=tomchristie --data is_admin=true
 ## Authentication & headers
 The `credentials` command is used to manage the request `Authentication:` header.
 Any credentials added are always linked to a particular domain, so as to ensure
 that credentials are not leaked across differing APIs.
 The format for adding a new credential is:
    $ coreapi credentials add <domain> <credentials string>
 For instance:
    $ coreapi credentials add api.example.org "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
 The optional `--auth` flag also allows you to add specific types of authentication,
 handling the encoding for you. Currently only `"basic"` is supported as an option here.
 For example:
    $ coreapi credentials add api.example.org tomchristie:foobar --auth basic
 You can also add specific request headers, using the `headers` command:
    $ coreapi headers add api.example.org x-api-version 2
 For more information and a listing of the available subcommands use `coreapi
 credentials --help` or `coreapi headers --help`.
 ## Codecs
 By default the command line client only includes support for reading Core JSON
 schemas, however it includes a plugin system for installing additional codecs.
    $ pip install openapi-codec jsonhyperschema-codec hal-codec
    $ coreapi codecs show
    Codecs
    corejson        application/vnd.coreapi+json encoding, decoding
    hal             application/hal+json         encoding, decoding
    openapi         application/openapi+json     encoding, decoding
    jsonhyperschema application/schema+json      decoding
    json            application/json             data
    text            text/*                       data
 ## Utilities
 The command line client includes functionality for bookmarking API URLs
 under a memorable name. For example, you can add a bookmark for the
 existing API, like so...
    $ coreapi bookmarks add accountmanagement
 There is also functionality for navigating forward or backward through the
 history of which API URLs have been accessed.
    $ coreapi history show
    $ coreapi history back
 For more information and a listing of the available subcommands use
 `coreapi bookmarks --help` or `coreapi history --help`.
 ## Other commands
 To display the current `Document`:
    $ coreapi show
 To reload the current `Document` from the network:
    $ coreapi reload
 To load a schema file from disk:
    $ coreapi load my-api-schema.json --format corejson
 To dump the current document to console in a given format:
    $ coreapi dump --format openapi
 To remove the current document, along with all currently saved history,
 credentials, headers and bookmarks:
    $ coreapi clear
 ---
 # Python client library
 The `coreapi` Python package allows you to programmatically interact with any
 API that exposes a supported schema format.
 ## Getting started
 You'll need to install the `coreapi` package using `pip` before you can get
 started.
    $ pip install coreapi
 In order to start working with an API, we first need a `Client` instance. The
 client holds any configuration around which codecs and transports are supported
 when interacting with an API, which allows you to provide for more advanced
 kinds of behavior.
    import coreapi
    client = coreapi.Client()
 Once we have a `Client` instance, we can fetch an API schema from the network.
    schema = client.get('https://api.example.org/')
 The object returned from this call will be a `Document` instance, which is
 a representation of the API schema.
 ## Authentication
 Typically you'll also want to provide some authentication credentials when
 instantiating the client.
 #### Token authentication
 The `TokenAuthentication` class can be used to support REST framework's built-in
 `TokenAuthentication`, as well as OAuth and JWT schemes.
    auth = coreapi.auth.TokenAuthentication(
        scheme='JWT',
        token='<token>'
    )
    client = coreapi.Client(auth=auth)
 When using TokenAuthentication you'll probably need to implement a login flow
 using the CoreAPI client.
 A suggested pattern for this would be to initially make an unauthenticated client
 request to an "obtain token" endpoint
 For example, using the "Django REST framework JWT" package
    client = coreapi.Client()
    schema = client.get('https://api.example.org/')
    action = ['api-token-auth', 'create']
    params = {"username": "example", "password": "secret"}
    result = client.action(schema, action, params)
    auth = coreapi.auth.TokenAuthentication(
        scheme='JWT',
        token=result['token']
    )
    client = coreapi.Client(auth=auth)
 #### Basic authentication
 The `BasicAuthentication` class can be used to support HTTP Basic Authentication.
    auth = coreapi.auth.BasicAuthentication(
        username='<username>',
        password='<password>'
    )
    client = coreapi.Client(auth=auth)
 ## Interacting with the API
 Now that we have a client and have fetched our schema `Document`, we can now
 start to interact with the API:
    users = client.action(schema, ['users', 'list'])
 Some endpoints may include named parameters, which might be either optional or required:
    new_user = client.action(schema, ['users', 'create'], params={"username": "max"})
 ## Codecs
 Codecs are responsible for encoding or decoding Documents.
 The decoding process is used by a client to take a bytestring of an API schema
 definition, and returning the Core API `Document` that represents that interface.
 A codec should be associated with a particular media type, such as `'application/coreapi+json'`.
 This media type is used by the server in the response `Content-Type` header,
 in order to indicate what kind of data is being returned in the response.
 #### Configuring codecs
 The codecs that are available can be configured when instantiating a client.
 The keyword argument used here is `decoders`, because in the context of a
 client the codecs are only for *decoding* responses.
 In the following example we'll configure a client to only accept `Core JSON`
 and `JSON` responses. This will allow us to receive and decode a Core JSON schema,
 and subsequently to receive JSON responses made against the API.
    from coreapi import codecs, Client
    decoders = [codecs.CoreJSONCodec(), codecs.JSONCodec()]
    client = Client(decoders=decoders)
 #### Loading and saving schemas
 You can use a codec directly, in order to load an existing schema definition,
 and return the resulting `Document`.
    input_file = open('my-api-schema.json', 'rb')
    schema_definition = input_file.read()
    codec = codecs.CoreJSONCodec()
    schema = codec.load(schema_definition)
 You can also use a codec directly to generate a schema definition given a `Document` instance:
    schema_definition = codec.dump(schema)
    output_file = open('my-api-schema.json', 'rb')
    output_file.write(schema_definition)
 ## Transports
 Transports are responsible for making network requests. The set of transports
 that a client has installed determines which network protocols it is able to
 support.
 Currently the `coreapi` library only includes an HTTP/HTTPS transport, but
 other protocols can also be supported.
 #### Configuring transports
 The behavior of the network layer can be customized by configuring the
 transports that the client is instantiated with.
    import requests
    from coreapi import transports, Client
    credentials = {'api.example.org': 'Token 3bd44a009d16ff'}
    transports = transports.HTTPTransport(credentials=credentials)
    client = Client(transports=transports)
 More complex customizations can also be achieved, for example modifying the
 underlying `requests.Session` instance to [attach transport adaptors][transport-adaptors]
 that modify the outgoing requests.
 ---
 # JavaScript Client Library
 The JavaScript client library allows you to interact with your API either from a browser, or using node.
 ## Installing the JavaScript client
 There are two separate JavaScript resources that you need to include in your HTML pages in order to use the JavaScript client library. These are a static `coreapi.js` file, which contains the code for the dynamic client library, and a templated `schema.js` resource, which exposes your API schema.
 First, install the API documentation views. These will include the schema resource that'll allow you to load the schema directly from an HTML page, without having to make an asynchronous AJAX call.
    from rest_framework.documentation import include_docs_urls
    urlpatterns = [
        ...
        path('docs/', include_docs_urls(title='My API service'), name='api-docs'),
    ]
 Once the API documentation URLs are installed, you'll be able to include both the required JavaScript resources. Note that the ordering of these two lines is important, as the schema loading requires CoreAPI to already be installed.
    <!--
        Load the CoreAPI library and the API schema.
        /static/rest_framework/js/coreapi-0.1.1.js
        /docs/schema.js
    -->
    {% load static %}
    <script src="{% static 'rest_framework/js/coreapi-0.1.1.js' %}"></script>
    <script src="{% url 'api-docs:schema-js' %}"></script>
 The `coreapi` library, and the `schema` object will now both be available on the `window` instance.
    const coreapi = window.coreapi;
    const schema = window.schema;
 ## Instantiating a client
 In order to interact with the API you'll need a client instance.
    var client = new coreapi.Client();
 Typically you'll also want to provide some authentication credentials when
 instantiating the client.
 #### Session authentication
 The `SessionAuthentication` class allows session cookies to provide the user
 authentication. You'll want to provide a standard HTML login flow, to allow
 the user to login, and then instantiate a client using session authentication:
    let auth = new coreapi.auth.SessionAuthentication({
        csrfCookieName: 'csrftoken',
        csrfHeaderName: 'X-CSRFToken',
    });
    let client = new coreapi.Client({auth: auth});
 The authentication scheme will handle including a CSRF header in any outgoing
 requests for unsafe HTTP methods.
 #### Token authentication
 The `TokenAuthentication` class can be used to support REST framework's built-in
 `TokenAuthentication`, as well as OAuth and JWT schemes.
    let auth = new coreapi.auth.TokenAuthentication({
        scheme: 'JWT',
        token: '<token>',
    });
    let client = new coreapi.Client({auth: auth});
 When using TokenAuthentication you'll probably need to implement a login flow
 using the CoreAPI client.
 A suggested pattern for this would be to initially make an unauthenticated client
 request to an "obtain token" endpoint
 For example, using the "Django REST framework JWT" package
    // Setup some globally accessible state
    window.client = new coreapi.Client();
    window.loggedIn = false;
    function loginUser(username, password) {
        let action = ["api-token-auth", "obtain-token"];
        let params = {username: username, password: password};
        client.action(schema, action, params).then(function(result) {
            // On success, instantiate an authenticated client.
            let auth = window.coreapi.auth.TokenAuthentication({
                scheme: 'JWT',
                token: result['token'],
            })
            window.client = coreapi.Client({auth: auth});
            window.loggedIn = true;
        }).catch(function (error) {
            // Handle error case where eg. user provides incorrect credentials.
        })
    }
 #### Basic authentication
 The `BasicAuthentication` class can be used to support HTTP Basic Authentication.
    let auth = new coreapi.auth.BasicAuthentication({
        username: '<username>',
        password: '<password>',
    })
    let client = new coreapi.Client({auth: auth});
 ## Using the client
 Making requests:
    let action = ["users", "list"];
    client.action(schema, action).then(function(result) {
        // Return value is in 'result'
    })
 Including parameters:
    let action = ["users", "create"];
    let params = {username: "example", email: "example@example.com"};
    client.action(schema, action, params).then(function(result) {
        // Return value is in 'result'
    })
 Handling errors:
    client.action(schema, action, params).then(function(result) {
        // Return value is in 'result'
    }).catch(function (error) {
        // Error value is in 'error'
    })
 ## Installation with node
 The coreapi package is available on NPM.
    $ npm install coreapi
    $ node
    const coreapi = require('coreapi')
 You'll either want to include the API schema in your codebase directly, by copying it from the `schema.js` resource, or else load the schema asynchronously. For example:
    let client = new coreapi.Client();
    let schema = null;
    client.get("https://api.example.org/").then(function(data) {
        // Load a CoreJSON API schema.
        schema = data;
        console.log('schema loaded');
    })
 [heroku-api]: https://devcenter.heroku.com/categories/platform-api
 [heroku-example]: https://www.coreapi.org/tools-and-resources/example-services/#heroku-json-hyper-schema
 [core-api]: https://www.coreapi.org/
 [schema-generation]: ../api-guide/schemas.md
 [transport-adaptors]: http://docs.python-requests.org/en/master/user/advanced/#transport-adapters
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -53,7 +53,6 @@ nav:
    - 'Settings': 'api-guide/settings.md'
 - Topics:
     - 'Documenting your API': 'topics/documenting-your-api.md'
     - 'API Clients': 'topics/api-clients.md'
     - 'Internationalization': 'topics/internationalization.md'
     - 'AJAX, CSRF & CORS': 'topics/ajax-csrf-cors.md'
     - 'HTML & Forms': 'topics/html-and-forms.md'