金蝶云苍穹OpenAPI开发规范

应用程序编程接口（Application Programming Interface，API接口），是应用程序重要的组成部分，就是应用程序对外提供了一个操作数据的入口，这个入口可以是一个函数或类方法，也可以是一个url地址或者一个网络地址。当客户端调用这个入口，应用程序则会执行对应代码操作，给客户端完成相对应的功能。

通过苍穹OpenAPI进行接口开发，从设计API阶段开始，需要进行优雅的设计，帮助API使用者更好地了解、使用和集成，同时可以有效地维护它，才能让我们在集成项目中事半功倍。本篇文档作为API开发指导手册，包含四部分规范：API配置规范、API调用规范、API错误码规范和API安全规范。

苍穹平台OpenAPI开发规范.pdf

1. API配置规范

部署OpenAPI时其传输协议应选择 HTTPS 协议，以确保传输数据的安全性。 默认报文格式为JSON，报文格式由具体服务接口定义。

1.1 请求URL

开放平台注册的接口地址为URI，拼接域名/kapi 组成完整请求地址，如：https://feature.kingdee.com:1026/dev/kapi/v2/kdtest/pm/pm_purorderbill/save。

1.2 请求方式

调用接口的请求方式主要有GET和POST。

• GET请求主要用于向指定的资源发出“显示"请求。使用GET方法应该只用在获取数据，但是传递的参数则显示在地址栏，安全性低，且参数的长度也有限制（2048字符）；

• POST请求则用于向指定资源提交数据，请求服务器进行处理例如保存单据或基础资料。这个请求可能会创建新的资源或修改现有资源，或二者皆有。将传递的参数放在request body中，不会在地址栏显示，安全性比get请求高，参数没有长度限制。

1.3 整体规范

同时为保证API兼容性，接口维护时还有以下注意事项：

1) API一旦发布，新版本必须保证向下兼容。业务逻辑的变动，不应影响接口的调用，以避免引发生产事故。

2) API出入参名、类型在新版本中不得更改，不可删除。如果要变更参数类型 或 新增必填参数时应当创建一个新版本的API。如在API编码上增加版本标识如：save/ver2。

3) 所有二开的API接口，建议打开第三方应用授权开关；查询操作API，建议打开启用查询权限控制开关

4) API升级如果需要增加入参，必须设置默认值，否则无法做到向下兼容性。

5) API校验逻辑必须写在操作插件中，不可以写在页面插件中。API引擎不会执行页面插件逻辑。

6) 每个接口应开发配套的自动化单元测试用例。

2. API调用规范

在客户端调用API接口过程中常见的有高频调用、大批量数据和幂等性问题，其中大批量数据保存，由于一次查询或保存的数据量太大，很可能会造成接口超时问题。

幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。

在实际的项目上，如果出现高并发或网络异常的情况，例如Nginx在网络异常时会重复转发请求，可能会生成重复生成数据或多次提交请求的。比如订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，很可能就出现多扣一次库存的情况。

因此为保证接口可靠性和稳定性，客户端在调用时应遵守相关规范。