第十六章 源代码文件 REST API 教程（一）

本章提供了一个简短的教程，通过一系列示例演示如何使用源代码文件 REST API。它包含以下部分：

API 基础

Atelier 用于访问 IRIS 源代码文件的 API 使用 REST 架构风格。 REST 的名字来源于“Representational State Transfer”。与许多 REST API 一样 IRIS 源代码文件 REST API 使用 HTTP GET、POST、PUT、DELETE 和 HEAD 方法，并将 JSON 用于传入和传出消息体。

要调用 API 方法，需要了解以下内容：
- HTTP 方法——它是以下之一：GET、POST、PUT、DELETE 或 HEAD。
- HTTP 标头——为调用提供上下文信息。此 API 中使用的 HEADERS 包括：
- 授权，它提供对服务器的访问。除非安装了具有最低安全性的服务器，否则需要提供用户名和密码才能访问 API。
- Content-Type application/json，指定入站负载以 JSON 格式提供。必须为所有 POST 和 PUT 方法指定此标头。
- If-None-Match，它允许 GetDoc 或 PutDoc 调用检查源代码文件自上次访问以来是否被修改。
- URL - URL 由以下部分组成：
- http://
- server-name:port-number/——在本章中，我们假设 IRIS 在本地服务器上运行并使用端口 52773。
- api/atelier/——这是由具有 %Api.Atelier 调度类的 Web 应用程序定义的。
- 标识方法和目标的 URL 部分。此部分可以包含固定文本和您指定用于标识命名空间、文档名称或类型的文本。

例如，标识 GetDocNames 方法的 URL 部分是 v1/namespace/docnames/。此方法从 MYNS 命名空间获取文档的完整 URL 为：

ttp://localhost:52773/api/atelier/v1/MYNS/docnames

标识 GetServer 方法的 URL 部分是一个空字符串，因此 GetServer 的完整 URL 是：

http://localhost:52773/api/atelier/

• URL 参数——修改调用。如果 API 方法有 URL 参数，它们会在参考部分中描述。
• 入站 JSON 有效负载 — POST 和 PUT 方法的入站消息格式。
• 出站 JSON 负载 — HTTP 方法返回的出站消息的格式。

获取有服务器的信息

通常，将进行的第一个 REST 调用是 GetServer 方法，该方法返回有关 IRIS 源代码文件 REST API 版本号和服务器上可用的命名空间的信息。

GET http://localhost:52773/api/atelier/

此调用返回以下 JSON 消息：

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "version": "IRIS for Windows (x86-64) 2018.1.1 (Build 515U) Mon Feb 5 2018 08:24:13 EST",
      "id": "98E1697E-13F9-4D6A-8B73-827873D1D61C",
      "api": 2,
      "features": [
...
      ],
      "namespaces": [
        "%SYS",
        "USER"
      ]
    }
    }
}

所有返回 JSON 消息的源代码文件 REST API 方法都使用相同的通用格式：

• status errors状态错误——通常是 源代码文件 REST API 以 HTTP 状态代码的形式返回错误。此字段在一些不寻常的情况下使用，并且此元素包含 %Status 值，该值可能包含多个错误的文本。
• status summary状态摘要—包含状态错误的摘要。
• console控制台—包含 将在控制台上为该操作显示的文本。
• result结果—包含方法的结果。

GetServer 方法在“结果result”元素中返回有关服务器的信息。结果元素包含一个值“内容”，其中包含：
- version版本—包含在服务器上运行的实例的版本字符串。
- id — 包含的实例 GUID。
- api—指定在这个版本的中实现的 源代码文件 REST API 的版本号。
- features—表示在此实例上启用的功能。
- namespaces命名空间—列出在服务器上定义的命名空间。

GetNamespace 方法返回有关指定命名空间的信息，包括映射到命名空间的数据库和每个数据库的哈希值。哈希对于提高与服务器通信的效率很有用。但是你可以通过GetServer返回的命名空间信息来获取命名空间中源代码文件的信息。