API Clients - Django REST framework

API客户端-Django REST框架

API客户端

API客户端处理如何发出网络请求和如何解码响应的基本细节。它们为开发人员提供了一个要处理的应用程序接口，而不是直接使用网络接口。

这里记录的API客户端不限于使用Django REST框架构建的API。它们可以与公开受支持的架构格式的任何API一起使用。

例如,Heroku平台API以JSON Hyperschema格式公开架构。因此，CoreAPI命令行客户端和PythonClient库可以是用于与Heroku API交互。.

客户端核心API

核心API是一种可用于描述API的文档规范。它可以在任何服务器端使用，就像REST框架的模式生成，或者使用客户端，如这里所述。

当使用客户端时，Core API允许动态驱动客户端库它可以与任何公开受支持的架构或超媒体格式的API交互。

与直接构建HTTP请求与API交互相比，使用动态驱动的客户机具有许多优点。

更有意义的互动

API交互以更有意义的方式呈现。您正在应用程序接口层工作，而不是网络接口层。

弹性与可进化性

客户端确定哪些端点可用，每个特定端点存在哪些参数，以及HTTP请求是如何形成的。

这也允许一定程度的API进化。可以在不破坏现有客户端的情况下修改URL，也可以在有线上使用更高效的编码，客户端可以透明地升级。

自描述性API

动态驱动的客户端能够向最终用户展示API上的文档。这个文档允许用户发现可用的端点和参数，并更好地理解他们正在使用的API。

因为这个文档是由API模式驱动的，所以它将始终是最新部署的服务版本的最新版本。

---

命令行客户端

命令行客户端允许您检查并与任何公开受支持的架构格式的API进行交互。

开始

若要安装CoreAPI命令行客户端，请使用pip.

注意，命令行客户端是python客户端库的单独包。确保安装coreapi-cli.

$ pip install coreapi-cli

要开始检查和与API交互，必须首先从网络加载模式。

$ 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)
}

然后，这将加载模式，并显示生成的Document...这，这个Document包括可能针对API进行的所有可用交互。

若要与API交互，请使用action命令。此命令需要用于索引到链接中的键列表。

$ coreapi action users list
[
    {
        "url": "http://127.0.0.1:8000/users/2/",
        "id": 2,
        "username": "aziz",
        "snippets": []
    },
    ...
]

若要检查底层HTTP请求和响应，请使用--debug旗子。

$ 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/"]}]

[
    ...
]

有些操作可能包括可选的或必需的参数。

$ coreapi action users create --param username=example

使用时--param，输入的类型将自动确定。

如果希望更明确地说明参数类型，请使用--data对于任何NULL、数值、布尔值、列表或对象输入，并使用--string用于字符串输入。

$ coreapi action users edit --string username=tomchristie --data is_admin=true

身份验证和标头

这个credentials命令用于管理请求。Authentication:头球。添加的凭据总是链接到特定的域，以确保凭据不会在不同的API之间泄漏。

添加新凭据的格式是：

$ coreapi credentials add <domain> <credentials string>

例如：

$ coreapi credentials add api.example.org "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"

任选--auth标志还允许您添加特定类型的身份验证，为您处理编码。目前只"basic"在这里支持作为一个选项。例如：

$ coreapi credentials add api.example.org tomchristie:foobar --auth basic

还可以使用headers指挥：

$ coreapi headers add api.example.org x-api-version 2

有关更多信息和可用子命令的列表，请使用coreapi credentials --help或coreapi headers --help.

编解码器

默认情况下，命令行客户机只支持读取CoreJSON模式，但是它包含一个用于安装附加编解码器的插件系统。

$ 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

公用事业

命令行客户端包含了在一个难忘的名称下对APIURL进行书签的功能。例如，您可以为现有的API添加一个书签，如下所示.

$ coreapi bookmarks add accountmanagement

还有一些功能可以在访问了API URL的历史记录中向前或向后导航。

$ coreapi history show
$ coreapi history back

有关更多信息和可用子命令的列表，请使用coreapi bookmarks --help或coreapi history --help.

其他命令

显示当前Document:

$ coreapi show

重新加载当前Document来自网络：

$ coreapi reload

若要从磁盘加载架构文件，请执行以下操作：

$ coreapi load my-api-schema.json --format corejson

以给定格式将当前文档转储到控制台：

$ coreapi dump --format openapi

若要删除当前文档以及所有当前保存的历史记录、凭据、标头和书签，请执行以下操作：

$ coreapi clear

---

Python客户端库

这个coreapiPython包允许您以编程方式与任何公开受支持的模式格式的API交互。

开始

您需要安装coreapi包装使用pip在你开始之前。

$ pip install coreapi

为了开始使用API，我们首先需要一个Client举个例子。客户端保存与API交互时支持编解码器和传输的任何配置，这允许您提供更高级的行为类型。

import coreapi
client = coreapi.Client()

一旦我们有了Client实例，我们可以从网络中获取一个API模式。

schema = client.get('https://api.example.org/')

此调用返回的对象将是Document实例，它是API架构的表示形式。

认证

通常，您还希望在实例化客户端时提供一些身份验证凭据。

令牌认证

这个TokenAuthentication类可用于支持REST框架的内置TokenAuthentication，以及OAuth和JWT计划。

auth = coreapi.auth.TokenAuthentication(
    scheme='JWT',
    token='<token>'
)
client = coreapi.Client(auth=auth)

在使用TokenAuthentication时，您可能需要使用CoreAPI客户端实现登录流。

建议的模式是最初向“获取令牌”端点发出未经身份验证的客户端请求。

例如，使用“Django REST框架JWT”包

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)

基本认证

这个BasicAuthentication类可用于支持HTTP基本身份验证。

auth = coreapi.auth.BasicAuthentication(
    username='<username>',
    password='<password>'
)
client = coreapi.Client(auth=auth)

与API交互

既然我们有了一个客户端，并且已经获取了我们的模式Document，我们现在可以开始与API交互：

users = client.action(schema, ['users', 'list'])

一些端点可能包括命名参数，这些参数可能是可选的，也可能是必需的：

new_user = client.action(schema, ['users', 'create'], params={"username": "max"})

编解码器

编解码器负责对文件进行编码或解码。

客户端使用解码过程获取API模式定义的字节串，并返回CoreAPIDocument代表这个界面。

编解码器应该与特定的媒体类型相关联，例如'application/coreapi+json'.

此媒体类型由服务器在响应中使用。Content-Type标头，以指示响应中返回的数据类型。

配置编解码器

可以在实例化客户端时配置可用的编解码器。这里使用的关键字参数是decoders，因为在客户端的上下文中，编解码器只用于解码答复。

在下面的示例中，我们将客户端配置为只接受Core JSON和JSON答复。这将允许我们接收和解码核心JSON模式，并随后接收针对API的JSON响应。

from coreapi import codecs, Client

decoders = [codecs.CoreJSONCodec(), codecs.JSONCodec()]
client = Client(decoders=decoders)

加载和保存模式

您可以直接使用编解码器来加载现有的模式定义，并返回生成的Document.

input_file = open('my-api-schema.json', 'rb')
schema_definition = input_file.read()
codec = codecs.CoreJSONCodec()
schema = codec.load(schema_definition)

您还可以直接使用编解码器生成架构定义。Document例如：

schema_definition = codec.dump(schema)
output_file = open('my-api-schema.json', 'rb')
output_file.write(schema_definition)

运输

传输负责提出网络请求。客户端已安装的传输集确定它能够支持哪些网络协议。

目前coreapi库只包含HTTP/HTTPS传输，但也可以支持其他协议。

配置传输

可以通过配置客户端实例化的传输来自定义网络层的行为。

import requests
from coreapi import transports, Client

credentials = {'api.example.org': 'Token 3bd44a009d16ff'}
transports = transports.HTTPTransport(credentials=credentials)
client = Client(transports=transports)

还可以实现更复杂的自定义，例如修改基础requests.Session实例到附加运输适配器来修改发出的请求。

---

JavaScript客户端库

JavaScript客户端库允许您通过浏览器或使用节点与API交互。

安装JavaScript客户端

为了使用JavaScript客户机库，需要在HTML页面中包含两个单独的JavaScript资源。这些是静态的coreapi.js文件，其中包含动态客户端库的代码和模板。schema.js资源，它公开API架构。

首先，安装API文档视图。这些资源将包括允许直接从HTML页面加载模式的模式资源，而不必进行异步Ajax调用。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title='My API service'))
]

一旦安装了API文档URL，您就可以包含这两个所需的JavaScript资源。注意，这两行的顺序很重要，因为模式加载要求CoreAPI已经安装好了。

<!--
    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>

这个coreapi图书馆，以及schema对象现在都可以在window举个例子。

const coreapi = window.coreapi
const schema = window.schema

实例化客户端

为了与API交互，您需要一个客户端实例。

var client = new coreapi.Client()

通常，您还希望在实例化客户端时提供一些身份验证凭据。

会话认证

这个SessionAuthentication类允许会话cookie提供用户身份验证。您需要提供一个标准的HTML登录流，以允许用户登录，然后使用会话身份验证实例化客户端：

let auth = new coreapi.auth.SessionAuthentication({
    csrfCookieName: 'csrftoken',
    csrfHeaderName: 'X-CSRFToken'
})
let client = new coreapi.Client({auth: auth})

身份验证方案将处理对不安全的HTTP方法的任何传出请求中包含一个CSRF报头。

令牌认证

这个TokenAuthentication类可用于支持REST框架的内置TokenAuthentication，以及OAuth和JWT计划。

let auth = new coreapi.auth.TokenAuthentication({
    scheme: 'JWT'
    token: '<token>'
})
let client = new coreapi.Client({auth: auth})

在使用TokenAuthentication时，您可能需要使用CoreAPI客户端实现登录流。

建议的模式是最初向“获取令牌”端点发出未经身份验证的客户端请求。

例如，使用“Django REST框架JWT”包

// 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: "example", email: "example@example.com"}
    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.
    })
}

基本认证

这个BasicAuthentication类可用于支持HTTP基本身份验证。

let auth = new coreapi.auth.BasicAuthentication({
    username: '<username>',
    password: '<password>'
})
let client = new coreapi.Client({auth: auth})

使用客户端

提出请求：

let action = ["users", "list"]
client.action(schema, action).then(function(result) {
    // Return value is in 'result'
})

包括参数：

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'
})

处理错误：

client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
}).catch(function (error) {
    // Error value is in 'error'
})

节点安装

Coreapi软件包可在国家预防机制上使用。

$ npm install coreapi
$ node
const coreapi = require('coreapi')

您可以将API模式直接包含在代码库中，方法是从schema.js资源，否则将异步加载架构。例如：

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')
})