携手创作,共同成长!这是我参与「掘金日新计划 · 9 月更文挑战」的第8天,点击查看活动详情
第十六章 源代码文件 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
返回的命名空间信息来获取命名空间中源代码文件的信息。