RESTful API 概述

JSA 和 API 版本

每个 JSA 版本都有一个 REST API 版本，如下表所述：

API 端点

API 终端节点 包含您要访问的资源的 URL 以及要对该资源完成的操作。操作由请求的 HTTP 方法指示：GET、POST、PUT 或 DELETE。

访问 API 所需的权限

身份验证信息必须作为 HTTP 标头包含在每个 API 请求中。通过以下方式之一提供所需的访问凭据：

• 在授权头中指定的 JSA 用户的用户名和密码。

  通过使用 HTTP 基本身份验证指定用户名和密码。尽管您可以通过为每个请求提供用户名和密码来发出 API 请求，但请对与 JSA 的所有 API 集成使用授权服务令牌。仅支持用户名和密码选项来查看文档页面。

  有关创建用户角色、安全配置文件和用户的更多信息，请参阅《 瞻博网络安全分析管理指南》。

• 在 SEC 标头中指定的授权服务令牌。

  若要作为授权服务进行身份验证，请创建使用授权服务的身份验证令牌。 JSA 授权服务分配了角色和安全配置文件，用于控制对各种 API 资源的访问。

  令牌在创建授权服务时指定的到期日期之前有效。

  有关创建用户角色、安全配置文件和授权服务的更多信息，请参阅《 瞻博网络安全分析管理指南》。

API 请求和响应

当您发送 API 请求时，服务器会返回 HTTP 响应。HTTP 响应包含一个状态代码，用于指示请求是否成功以及响应正文中响应的详细信息。大多数资源将此响应格式化为 JavaScript 对象表示法 （JSON）。您可以使用内置于用于提取数据的编程语言中的 JSON 包或库。

版本头

您可以使用版本标头请求特定版本的 API。如果未提供版本标头，则使用最新版本的 API，这可能会在升级 JSA 时中断集成。如果每次使用 API 时都提供版本标头，则可以更轻松地升级到较新版本的 JSA，而不会中断 API 客户端。

API 使用语义版本控制的主要和次要组件。自然数用于指定 API 的主要版本，例如“3”。API 的次要版本使用主要和次要组件进行指定，例如“3.1”。您可以将版本标头设置为 API 的主要版本或次要版本。与现有版本兼容的更改以递增的次要版本号引入。任何不兼容的更改都会以主要版本号增量引入。

如果在版本标头中指定了 API 的主要版本而没有次要组件，服务器将使用主要 API 版本中的最新次要版本进行响应。例如，如果客户端请求版本“3”，服务器将使用版本“3.1”进行响应。如果要使用 3.0 版，则必须在版本标头中请求“3.0”。如果请求的版本高于终端节点的最新版本，则会返回该终端节点的最新可用版本。每个终结点都列在其有效的每个版本下，即使在较新版本中保持不变也是如此。

端点弃用

API 终端节点标记为 已弃用 ，以指示不建议使用它，并将在未来版本中删除。为了让集成有时间使用替代方案，已弃用的端点在被删除之前至少会继续运行 1 个版本。交互式 API 文档页面指示终端节点已标记为已弃用。此外，已弃用终结点的 API 响应消息包括标头 Deprecated。可以将单个 API 终端节点或整个版本的 API 终端节点标记为已弃用。已弃用的终结点仍将继续运行，直到它们被删除。

当 API 终端节点完成弃用过程时，会将其移除。已删除的终结点不再成功响应。尝试调用已删除的终结点将返回错误。 HTTP 410 Gone 对于单个已删除的终结点，将返回响应。 HTTP 422 Unprocessable Entity 对于不再受支持的版本的请求，将返回响应。

在 API 请求中包含版本标头以调用特定版本的 API 终端节点。不支持未显式请求特定版本的 API 集成。如果未指定版本，则请求将定向到最新的可用版本。如果版本包含新的、不兼容的终结点版本，则集成可能会中断。将请求版本放在代码中的一个位置，以便在新版本可用时轻松升级。