综述

本文档主要覆盖 XSwitch REST API 接口。这些 API 接口不仅支持通常的数据库增删改查，也支持实时呼叫控制，如自动外呼接口、会议外呼接口等。

本文档不包含XCC API，后者提供更好的实时呼叫控制接口和集群功能。

XSwitch 是一个电信级的 IP 电话软交换系统和综合实时音视频多媒体通信平台。

XSwitch 支持电话、传真、视频会议、呼叫中心等。支持主流的通信协议如 SIP、H323、WebRTC、RTMP 等，支持单机部署、云原生集群部署，支持无限扩容及动态伸缩。目标是为用户提供一站式语音、视频、会议解决方案，可以作为 IP-PBX、视频会议服务器、传真服务器、多协议网关、呼叫中心服务器等使用。XSwitch 提供 REST、Websocket 二次开发接口。XSwitch 基于开源技术构建，如 FreeSWITCH、PostgreSQL、Nginx 等。

XSwitch 是模块化，积木式按需叠加和无限伸缩扩容的通信产品，更可以通过定制支持集群部署，实现更强大的功能。XSwitch 的位置、组件和逻辑关系如下图所示：

XSwitch 后台使用 C、Lua 等语言开发，数据库为 PostgreSQL，部分数据库（表）也支持 SQLite。

REST（Representational State Transfer 表述性状态转移）是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

REST 相对于 SOAP 或 XML-RPC 的 Web Service 来讲明显的更加简洁，效率更高。

RESTful Web 服务（也称为 RESTful Web API）是一个使用 HTTP 并遵循 REST 原则的 Web 服务。它从以下三个方面资源进行定义：

• URI，比如：http://example.com/resources/ 。
• Web 服务接受与返回的互联网媒体类型，比如：TXT、JSON、XML、YAML 等。
• Web 服务在该资源上所支持的一系列请求方法（比如：POST、GET、PUT/PATCH 或 DELETE）。

REST 的优点：

• 可以利用缓存（Cache）来提高响应速度
• 通讯本身的无状态性可以让不同的服务器的处理一系列请求中的不同请求，提高服务器的扩展性
• 浏览器即可作为客户端，简化软件需求
• 相对于其他叠加在 HTTP 协议之上的机制，REST 的软件依赖性更小
• 不需要额外的资源发现机制
• 在软件技术演进中的长期的兼容性更好

为方便解释，以下示例用 cURL 方式描述。

curl http://www.google.com

curl -XPUT http://192.168.1.100:8080

curl -XPUT -d "username=someone&password=1234" http://192.168.1.10:8080

curl -d '{"username": "someone"}' -H "Content-Type: application/json" http://192.168.1.10:8080

curl --basic --user username:password http://........

curl -v http://.....

cURL[^curl]是利用 URL 语法在命令行方式下工作的文件传输工具。

[^curl]: 参见 https://curl.haxx.se/ 。

它支持很多协议：FTP、FTPS、HTTP、HTTPS、GOPHER、TELNET、DICT、FILE 以及 LDAP。 cURL 同样支持 HTTPS 认证，HTTP POST 方法，HTTP PUT 方法，FTP 上传，Kerberos 认证，HTTP 上传， 代理服务器，cookies，用户名/密码认证，下载文件断点续传，上载文件断点续传，HTTP 代理服务器管道（ proxy tunneling），甚至它还支持 IPv6， Socks5 代理服务器，通过 HTTP 代理服务器上传文件到 FTP 服务器等等，功能十分强大。

传统的 HTTP 协议是单向的，而现代化丰富的应用需要在服务端和客户端实时的交换信息，这就需要一个双向的传输通道，Websocket 就是为了这一需求而生的。它在普通 HTTP 协议的基础上，通过 Upgrade 操作升级为一个双向的 Socket 长连接。

除非有特殊说明，所有编码都使用 UTF-8 编码。

• 查询类接口使用 GET 请求，创建类使用 POST 请求，修改、动作类使用 PUT 请求。
• 在本系统中，不使用 PATCH 请求。
• 必选参数一般以粗体标出。
• HTTP 返回状态码200为正常，其它为错误。
• HTTP 默认返回 JSON 格式信息，除非有特殊说明。
• 可以配置使用 HTTP Basic 验证，或不验证，或基于 Cookie 的验证。
• 接口分为同步模式和异步模式。缺省为同步模式。
  • 异步模式：在该模式下，发送 HTTP API 请求将生成一个后台任务(Background Job)并立即返回结果（包含 Background Job UUID）。这种模式执行速度快，但不知道是否执行成功。
  • 同步模式：在该模式下，HTTP 请求会阻塞，直到命令执行成功或失败后才返回，超时时间默认是 60 秒。
• 示例中由于排版限制，太长的命令行后面使用“\”续行符号，表示紧接着的下一行内容应该位于同一行。与典型的 UNIX 续行符兼容，可以直接 Copy & Paste。
• 系统会返回 HTTP 状态码，具体内容会在正文中（Body）中给出，正文的类型由 Content-Type 决定。有些 API 为了简单起见没有正文。

系统根据不同情况会返回HTTP 状态码[^httpcode]，简要描述如下：

[^httpcode]: 参见 https://baike.baidu.com/item/HTTP状态码 。

一般情况下，在执行成功后，系统将直接返回 HTTP 状态码200 OK，数据内容直接放在 Body 中。

有些 API，在获取 HTTP 状态码后，如果需要获取进一步的出错信息，则将在 Body 中返回更进一步的信息。格式如下：

XUI 的 API 状态码分类

• XUI
• FreeSWITCH Hangup Cause Code Table
• SIP SIP 状态码

示例 JSON 消息：

• 获取单个资源，返回一个对象

{
  "id": 1,
  "name": "Seven"
}

• 获取多个资源，返回一个数组

[
  {
    "id": 1,
    "name": "Seven"
  },
  {
    "id": 2,
    "name": "Nine"
  }
]

• 有分页时，返回带分页的数据

{
  "rowCount": 10,
  "page": 1,
  "pageCount": 1,
  "data": [
    {
      "id": 1,
      "name": "Seven"
    },
    {
      "id": 2,
      "name": "Nine"
    }
  ]
}

• 对资源进行获取或更新有的 API 会返回

{
  "code": 200,
  "message": "success",
  "data": {}
}

其中，data可能是一个对象{}或数组[]。

• 对单一资源，创建成功返回对象id

{
  "id": 12
}

• 更新一个资源，返回对象的id
• 删除一个资源，返回被删除的id
• 删除一批资源，返回200 OK，原样返回请求id组成的数组。

有些 API，在 POST、PUT、DELETE 请求时增加pleaseResponseWithFullObject=true参数（在 JSON 中或urlencod的字符串中，这个名字是特别选定的，以免跟现有的冲突），会返回整个对象。注意该参数仅在某些 API 中支持。

系统根据不同情况会返回对应状态码与消息对，简要描述如下：

后台的 HTTP Server 是一个简单实现。因此，未对输入参数做严格的完整性检查，也没有检查所有错误的情况。在极端情况下，HTTP Server 端可能会在后端抛出异常并没有任何消息返回。

系统支持HTTP/1.0和HTTP/1.1。后者可以在同一 Socket 连接上发起多个请求，但是，在后台异常的情况下可能不会响应所有请求。在排错时可以使用HTTP/1.0重试。在 cURL 中使用HTTP/1.0的参数为：

curl -0 -vvv http://...

前后台的数据交互格式。

对于单个数据，使用 Object 形式描述，对于多个类似的数据，使用 Object 数组形式描述，如：

{ "username": "Seven" }

[{ "username": "Seven" }, { "username": "Eleven" }]

REST API 按照标准的 REST 访问方式设计，即 URL 是一个资源，对资源可以有 POST、PUT、GET、DELETE 等四种动作，分别对应数据库里的 CURD 操作。一“些”资源一般是以复数表示的，如：

GET /api/extensions

单个资源则以单数表示，如：

GET /api/extensions/$uuid

其中，对于调度 API 类的接口，有些并没有全部的 CURD 对应。

注意：在上面的例子中，$uuid表示是一个变量，在实际使用时要用实际的 Channel UUID 代替。

操作使用 REST 接口。以用户操作为例（注意，以下内容仅为方便说明，实际的返回数据中分有分页相关的数据）。

获取所有用户，结果以 JSON 数组形式返回，找不到返回空数组“[]”：

GET /api/users

获取单个用户，返回一个 JSON Object，找不到返回 404

GET /api/users/1

修改用户，返回被修改的 ID 对象，如 “{"id": 3}”。

PUT /api/users/1

创建用户，返回新建的用户id，如：

POST /api/users

{ "id": 7 }

删除用户，返回被删除的用户 ID 对象，如{"id": 1}：

DELETE /api/users/1

{ "id": 1 }

有些情况下，需要使用 Scoped API，即操作是有作用域的。如

PUT /api/sip_profiles/1/params/2

在上述操作中，我们需要修改id为2的参数param，但是，只有该param隶属于id为1的sip_profile时才可以修改，以防止误操作。在后台实现时，应构造类似如下的 SQL 语句：

UPDATE sip_profiles set ... WHERE sip_profile_id = 1 AND param_id = 2

请求：

GET /api/users?page=1&perPage=10

• page：第几页
• perPage：每页返回多少行

返回：

{
  "rowCount": 10,
  "page": 1,
  "pageCount": 1,
  "data": [
    {
      "id": 1,
      "name": "Seven"
    },
    {
      "id": 2,
      "name": "Nine"
    }
  ]
}

• rowCount：行数
• page：当前页
• pageCount：共几页

注意： 以下相关文件暂时没有维护，如果您愿意帮助我们，请与我们联系。

API 支持以下测试工具。

使用 Postman 接口测试工具，通过用户名和密码获取 token，带着 token 可对系统接口进行增删改查。

请导入xui-api.OpenAPI3.yaml，并修改servers - urls - example.com和其他参数。