From 44c3e5fd5ee08b5e8da9414138b31e4154a8ffb9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 13 Jul 2016 14:41:22 +0100 Subject: [PATCH] Update release documentation --- docs/topics/3.4-announcement.md | 46 +++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/topics/3.4-announcement.md b/docs/topics/3.4-announcement.md index eb9370877..d3af44298 100644 --- a/docs/topics/3.4-announcement.md +++ b/docs/topics/3.4-announcement.md @@ -50,21 +50,46 @@ Right now we're over 60% of the way towards achieving that. REST framework 3.4 brings built-in support for generating API schemas. -We're able to provide this support in a format-independent manner by using -[Core API][core-api], a Document Object Model for describing APIs. +We provide this support by using [Core API][core-api], a Document Object Model +for describing APIs. -Taking this approach means that we're able to support numerous different -output formats for our API schemas, and should also open the door to a range -of auto-generated API documentation options in the future. +Because Core API represents the API schema in an format-independent +manner, we're able to render the Core API `Document` object into many different +schema formats, by allowing the renderer class to determine how the internal +representation maps onto the external schema format. + +This approach should also open the door to a range of auto-generated API +documentation options in the future, by rendering the `Document` object into +HTML documentation pages. Alongside the built-in schema support, we're also now providing the following: -* A command line tool for interacting with APIs. -* A Python client library for interacting with APIs. +* A [command line tool][command-line-client] for interacting with APIs. +* A [Python client library][client-library] for interacting with APIs. These API clients are dynamically driven, and able to interact with any API that exposes a supported schema format. +Dynamically driven clients allow you to interact with an API at an application +layer interface, rather than a network layer interface, while still providing +the benefits of RESTful Web API design. + +We're expecting to expand the range of languages that we provide client libraries +for over the coming months. + +--- + +Current support for schema formats is as follows: + +Name | Support | PyPI package +---------------------------------|-------------------------------------|-------------------------------- +[Core JSON][core-json] | Schema generation & client support. | Built-in support in `coreapi`. +[Swagger / OpenAPI][swagger] | Schema generation & client support. | The `openapi-codec` package. +[JSON Hyper-Schema][hyperschema] | Currrently client support only. | The `hyperschema-codec` package. +[API Blueprint][api-blueprint] | Not yet available. | Not yet available. + +--- + You can read more about any of this new functionality in the following: * New tutorial section on [schemas & client libraries][tut-7]. @@ -130,11 +155,16 @@ Many thanks to all our contributors who've been involved in the release, either The full set of itemized release notes [are available here][release-notes]. - [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [moss]: mozilla-grant.md [funding]: funding.md [core-api]: http://www.coreapi.org/ +[command-line-client]: api-clients#command-line-client +[client-library]: api-clients#python-client-library +[core-json]: http://www.coreapi.org/specification/encoding/#core-json-encoding +[swagger]: https://openapis.org/specification +[hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html +[api-blueprint]: https://apiblueprint.org/ [tut-7]: ../../tutorial/7-schemas-and-client-libraries/ [schema-generation]: ../../api-guide/schemas/ [api-clients]: api-clients.md