转载自：http://www.django-rest-framework.org/tutorial/7-schemas-and-client-libraries/

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.

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 including an autogenerated schema view in our URL configuration.

from rest_framework.schemas import get_schema_view

schema_view = get_schema_view(title='Pastebin API')

urlpatterns = [

    url(r'^schema/$', schema_view),

    ...

]

If you visit the API root endpoint in a browser you should now see corejson representation become available as an option.

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 encoding.

Other schema formats, such as Open API (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 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/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 on GitHub, or try out a live example in the 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:

Now go build awesome things.

Tutorial 7: Schemas & client libraries的更多相关文章

  1. Django REST framework 第七章 Schemas & client libraries

    模式是一个机器可读文档,描述可用的API端点,URL以及它们支持的操作. 模式对于自动生成文档是一个很有用的工具,也可以用来动态调用可以于API交互的客户端库. Core API 为了提供模式支持,R ...

  2. 编译pure-ftpd时提示错误Your MySQL client libraries aren't properly installed

    如果出现类似configure: error: Your MySQL client libraries aren’t properly installed 的错误,请将mysql目录下的 includ ...

  3. Attempt to load Oracle client libraries threw BadImageFormatException. This problem will occur when running in 64 bit mode with the 32 bit Oracle client components installed.

    System.Data.OracleClient 已经过时了.微软不再支持它. 因此,我建议你为. NET 使用Oracle数据提供程序:ODP.Net. 你可以从以下位置下载: 版本:Release ...

  4. Good Zookeeper Tutorial with Java client

    参考: https://stackoverflow.com/questions/33524537/good-zookeeper-tutorial-with-java-client I was tryi ...

  5. Kubernetes 的 Client Libraries 的使用

    说明 kubernetes 估计会成为 linux 一样的存在,client-go 是它的 go sdk,client-go/examples/ 给出了一些用例,但是数量比较少. api Resour ...

  6. django-rest-framework快速入门

    前言:第一次接触django-rest-framework是在实习的时候.当时也不懂,看到视图用类方法写的感觉很牛逼的样子.因为官网是英文的,这对我的学习还是有一点的阻力的,所以当时也没怎么学.真是太 ...

  7. django rest framework 详解

    Django REST framework 是用于构建Web API 的强大而灵活的工具包. 我们可能想使用REST框架的一些原因: Web浏览API对于开发人员来说是一个巨大的可用性. 认证策略包括 ...

  8. OData Client Code Generator

    转发. [Tutorial & Sample] How to use OData Client Code Generator to generate client-side proxy cla ...

  9. Awesome Go精选的Go框架，库和软件的精选清单.A curated list of awesome Go frameworks, libraries and software

    Awesome Go      financial support to Awesome Go A curated list of awesome Go frameworks, libraries a ...

随机推荐

  1. java 调试

    作为一名java开发程序员,或者有时候需要利用工具调试的时候,但是却感觉不会使用,其实只要记住四个键即可. 一般java开发工具使用的都是Eclipse或者MyEclipse,下面都有这几个键F5(进 ...

  2. Django文字教程

    user-----URL对应关系-------视图函数def func1()-------------- 函数给用户返回的实质上就是一个字符串,过程:通过open函数打开HTML,把HTML读到内存中 ...

  3. 关于kali linux系统的简单工具

    Linux系统中关于几个重要目录的原英文解释: /etc/: Contains configuration files of the installed tools /opt/: Contains M ...

  4. BZOJ4197 [Noi2015]寿司晚宴 【状压dp】

    题目链接 BZOJ4197 题解 两个人选的数都互质,意味着两个人选择了没有交集的质因子集合 容易想到将两个人所选的质因子集合作为状态\(dp\) \(n\)以内质数很多,但容易发现\(\sqrt{n ...

  5. <深入理解计算机系统>第七章读书笔记

    第七章读书笔记 链接 链接:将各种代码和数据部分收集起来并组合成为一个单一文件的过程.(这个文件可被加载或拷贝到存储器并执行) 链接可以执行于编译,加载或运行时. 静态链接: 两个主要任务: 1 符号 ...

  6. 【字符串】KMP字符串匹配

    百度百科 Definition \(KMP\)算法是一个字符串匹配算法.他接收两个字符串\(A,B\),返回\(B\)在\(A\)中出现的所有位置. 以下称需要被匹配的串\(A\)为主串,可能在主串中 ...

  7. HDU 4638 莫队算法

    Group Time Limit: 4000/2000 MS (Java/Others)    Memory Limit: 32768/32768 K (Java/Others)Total Submi ...

  8. Codeforces 938.C Constructing Tests

    C. Constructing Tests time limit per test 1 second memory limit per test 256 megabytes input standar ...

  9. Hdu5226 Tom and matrix

    Tom and matrix Time Limit: 3000/1500 MS (Java/Others)    Memory Limit: 65536/65536 K (Java/Others)To ...

  10. 手脱EZIP v1.0

    一.单步 1.载入PEID查壳 EZIP v1.0 2.载入OD,一上来就是一个大跳转,F8单步一直走 0040D0BE > $ /E9 jmp Notepad.004102DC ; //入口点 ...