转载自：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. 3.3 无连接运输：UDP

    3.3 无连接运输:UDP 简介: UDP提供不可靠的服务,它只做了运输层能做的最少工作,除了分解/复用以及少量的差错检测之外,几乎对IP没增加什么东西. 为什么应用开发人员宁愿再UDP之上构建应用, ...

  2. BMP图像直方图均衡算法（C语言大作业）

    万丈高楼平地起 C语言大作业 一.学习笔记篇 1.学习MarkDown MarkDown注重写作本身,而非花俏的界面 编辑器:vscode 插件:Markdown,Markdown Preview 2 ...

  3. BZOJ3261：最大异或和——题解

    http://www.lydsy.com/JudgeOnline/problem.php?id=3261 给定一个非负整数序列{a},初始长度为N. 有M个操作,有以下两种操作类型: 1.A x:添加 ...

  4. 洛谷P1242 新汉诺塔 【神奇的递归】

    题目描述 设有n个大小不等的中空圆盘,按从小到大的顺序从1到n编号.将这n个圆盘任意的迭套在三根立柱上,立柱的编号分别为A.B.C,这个状态称为初始状态. 现在要求找到一种步数最少的移动方案,使得从初 ...

  5. 【CodeChef】Chef and Graph Queries

    Portal --> CC Chef and Graph Queries Solution 快乐数据结构题(然而好像有十分优秀的莫队+可撤销并查集搞法qwq) 首先考虑一种方式来方便一点地..计 ...

  6. CDOJ--1404

    原题链接:http://acm.uestc.edu.cn/problem.php?pid=1404 分析:定义dp[i][j]表示i位时最左边为j时的情况,那么dp[i][[j]可以由dp[i-1][ ...

  7. Codeforces 931.F Teodor is not a liar!

    F. Teodor is not a liar! time limit per test 1 second memory limit per test 256 megabytes input stan ...

  8. hashlib模块--加密

    用于加密相关的操作,3.x里代替了md5模块和sha模块,主要提供 SHA1, SHA224, SHA256, SHA384, SHA512 ,MD5 算法 import hashlib m = ha ...

  9. linux 版本查询

    原文 : http://www.ha97.com/2987.html 一.查看Linux内核版本命令(两种方法): 1.cat /proc/version [root@localhost ~]# ca ...

  10. [LeetCode] 24. Swap Nodes in Pairs ☆

    Given a linked list, swap every two adjacent nodes and return its head. For example, Given 1->2-& ...