subspace_openapi_client的Rust API客户端

简介

Subspace API基于REST，具有面向资源的URL，返回JSON编码的响应，并返回标准HTTP响应代码。

API的基本URL是： https://api.subspace.com/

命名规范

• 目前使用的版本名是： v1
  • 示例： https://api.subspace.com/v1

身份验证

API令牌

Subspace使用JWT Bearer令牌对API请求进行身份验证。要使用任何Subspace API，您必须在每个请求中传递一个Bearer令牌。如果您在发起API请求时不包含Bearer令牌或使用错误或禁用的令牌，Subspace将返回错误。

Bearer令牌通过请求一个（如下所示）并出示您的可发布（client_id）和秘密（client_secret）令牌来授予。

Subspace提供两种类型的API令牌：可发布的（client_id）和秘密的（client_secret）。这些在Subspace控制台中可用。

• 可发布 API令牌（client_id）仅用于识别您的Subspace账户，它们不是秘密的。它们可以发布在您的网站JavaScript代码或iPhone或Android应用中。
• 秘密 API令牌（client_secret）应保密，并仅存储在您的服务器上。您的账户的秘密API令牌将允许您获取一个有效的JWT令牌，该令牌有权执行任何对Subspace的API请求。

获取JWT Bearer令牌

Subspace使用auth0进行JWT令牌管理。您可以通过使用https://id.subspace.com并遵循下面curl示例中的说明来获取JWT令牌。

保护您的API令牌

• JWT令牌的有效期为24小时。一旦过期，您将不得不使用Subspace的私有API和公共令牌来请求一个新的令牌。
• 子空间私有令牌可以在子空间控制台中进行轮换。
• 请保护好您的秘密令牌。您的秘密令牌可以代表您的账户进行任何API调用，包括可能影响账单的更改，如启用按量付费费用。请不要将您的秘密令牌存储在版本控制系统（如Git）中。请不要在您的Web服务器（如浏览器、移动应用或分布式文件）之外使用您的秘密令牌。
• 您可以使用子空间控制台获取API令牌。
• 您可以使用子空间控制台禁用按量付费。这可以防止由于未授权或异常使用而产生的意外费用。
• 不要直接在代码中嵌入API密钥。不要直接在您的应用程序代码中嵌入API密钥，而是将它们放在环境变量中或包含在单独存储的文件中（与应用程序代码的主要部分分开）——不在应用程序的源代码库中。这样，如果您分享您的代码，API密钥将不会包含在共享文件中。
• 不要在您的应用程序的源控制中存储API令牌。如果将API令牌存储在文件中，请将文件存储在您的应用程序的源控制系统之外。如果您使用的是公共源代码管理系统（如GitHub），这一点尤为重要。
• 使用受限令牌限制访问。子空间控制台将允许您指定与每个令牌关联的IP地址或引用URL，从而减少受损害的API令牌的影响。
• 为不同的应用使用独立的API令牌。这限制了每个令牌的作用范围。如果API令牌被损害，您可以轮换受影响的令牌，而不会影响其他API令牌。

错误代码

子空间使用HTTP响应代码来指示API请求的成功或失败。

一般HTML状态代码

• 2xx 成功。
• 基于请求中提供的信息的4xx错误。
• 子空间服务器上的5xx错误。

安全

我们为我们的API方法提供有效的、已签名的证书。请确保您的连接库支持带有SNI扩展的HTTPS。

REST操作指南

制作第一个REST API调用非常简单，您可以从浏览器中完成。您需要

• 在控制台中找到的您的秘密令牌和公共客户端令牌。
• 您想要请求的数据类型的URL。

首先，获取JWT Bearer令牌。命令行示例

curl --request POST \\
     --url \"https://id.subspace.com/oauth/token\" \\
     --header 'content-type: application/json' \\
     --data '{ \"client_id\": \"YOURCLIENTID\", \"client_secret\": \"YOURCLIENTSECRET\", \"audience\": \"https://api.subspace.com/\", \"grant_type\": \"client_credentials\" }'

REST调用由以下部分组成

• 基本URL：例如：https://api.subspace.com

• 版本：例如：v1

• API端点和任何参数：accelerator/acc_NDA3MUI5QzUtOTY4MC00Nz，其中acc_NDA3MUI5QzUtOTY4MC00Nz是一个有效的加速器ID

• 加速器ID始终具有以下格式：acc_NDA3MUI5QzUtOTY4MC00Nz，其中包含"acc_"前缀，后跟22个字符。

• 令牌头：所有REST请求都需要有效的JWT Bearer令牌，该令牌应作为“Authorization”头添加到请求中

  授权:BearerYOUR_TOKEN_HERE

授权头示例

如果您的API令牌为“my_api_token”，您将添加...

Authorization: Bearer my_api_token

...到头部。

命令行示例

使用令牌“my_api_token”列出您当前打开的packet_accelerators

curl -H “Authorization: Bearer my_api_token” https://api.subspace.com/v1/accelerator

或者，获取ID为'abcd-ef01-2345'的特定加速器的详细信息

curl -H “Authorization: Bearer my_api_token” https://api.subspace.com/v1/accelerator/abcd-ef01-2345

API版本控制

当我们对API进行向后不兼容的更改时，子空间将发布新版本。在发布新版本或停用旧版本之前，我们会提前通知。

向后兼容的更改

• 添加新的响应属性
• 添加新的端点
• 向现有端点添加新方法
• 添加新的查询字符串参数
• 添加新的路径参数
• 添加新的webhook事件
• 添加新的流式传输端点
• 更改现有响应属性的顺序

版本添加到基本URL，例如

• https://api.subspace.com/v1

当前版本是 v1: https://api.subspace.com/v1

更多信息，请访问 https://subspace.com

概览

此API客户端是由OpenAPI Generator项目生成的。通过从远程服务器使用openapi-spec，您可以轻松生成API客户端。

• API版本：1.0
• 包版本：1.0
• 构建包：org.openapitools.codegen.languages.RustClientCodegen

安装

将包放在项目文件夹下的subspace_openapi_client目录中，并在Cargo.toml中的[dependencies]

subspace_openapi_client = { path = "./subspace_openapi_client" }

API端点文档

所有URI都是相对于https://api.subspace.com

模型文档

• 正文
• Body1
• ProtobufAny
• V1Accelerator
• V1CreateSipTeleport
• V1ListAcceleratorResponse
• V1ListSipTeleportResponse
• V1NextPage
• V1SipTeleportResponse
• V1SipTeleportStatus
• V1TeleportAddresses
• V1TransportType
• V1UpdateSipTeleport
• V1WebRtcCdnResponse
• V1WebRtcCdnServer

要获取crate生成的文档，请使用

cargo doc --open

作者

[email protected]