第十六章 源代码文件 REST API 教程(一)
第十六章 源代码文件 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
返回的命名空间信息来获取命名空间中源代码文件的信息。