金蝶云苍穹OpenAPI开发规范

栏目：云苍穹知识作者：金蝶来源：金蝶云社区发布：2024-09-23浏览：1

金蝶云苍穹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编码	由英文、数字、下线划构成，动宾短语、语义化，如列表查询：getList、详情查询：getDetail、保存单据：save等，不允许出现非法及保留字符：如 $、%、#、%、&、+、~等
API名称	使用中英文，名称要准确、短小精炼，如查询供应商列表；批量保存采购订单
请求方式	GET/POST
分组	标准预置接口无需维护，为空
API状态	内测/发布/维护/禁用,对外发布的接口统一为发布状态
适用版本号	接口可运行的最低苍穹/星瀚版本号
开发商标识	标准预置接口的开发商标识统一为kingdee，ISV二开接口，URL会自动会带上ISV标识以与标准产品区隔
请求地址	生成规则：kapi/v2/{isv}/{appId}/{formId}/{API编码}，若为自定义API，url中没有formId段
详细描述	描述接口详细使用场景和用途
创建人和最近修改人	资源云预置接口为实际创建人和修改人，脚本预置接口统一为administrator
创建时间和最近修改时间	当前接口实际创建时间和修改时间
请求参数/返回参数	标准接口请求出入参时应遵守最小化原则，只发布必要的核心属性。非必要字段不要预置，敏感字段谨慎预置。保存API添加入参时，若字段为基础资料，只用勾选number或name等任一属性即可，不需要全部勾选
错误码	业务插件除返回Message这外，必须返回errorCode，以便被客户端程序做自动化处理在API管理界面维护本API的业务错误代码，并保持与代码的一致性，以便生成API文档
插件	自定义Java插件API，应使用强类型参数，不建议使用map弱类型。针对匿名访问的自定义API，在涉及到敏感信息的前提下，必须在插件中做好权限控制，否则容易出现横向越权（修改某个资源中其他用户的数据）或纵向越权（修改其他资源）

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

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

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

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

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

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

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

2. API调用规范

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

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

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

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

调用方规范	规范说明
Token及认证	目前支持5种认证方式：AccessToken 认证、摘要认证、JWT认证、基本认证和签名认证。使用accessToken认证时，有效期一般为120分钟，客户端应缓存token，不应每次调用API时重复请求获取token。认证方式详见社区帮助文档：OpenAPI认证指南。
重复调用控制	方案一（不推荐）：在每次请求时header中参数Idempotency-Key，客户端可生成一个随机值（比如SecurityRandom或guid），该值2小时内有效（V5.0.018版本后调整为30s）。当同一个请求第二次访问时，系统识别到重复的Idempotency-Key，证明重复提交了，系统会拒绝请求；该参数主要解决网络问题导致网关重复发送请求包问题，当并发极高时，建议在数据库建立唯一索引。适用版本：V5.0.005（BOS）以上方案二：在API配置界面打开防止重复请求开关。当调用接口时，若系统识别到完全相同的请求参数，30s内当同一个请求第二次访问时，系统会拒绝请求。适用版本：V5.0.018（BOS）以上
请求数据量控制	API服务端的业务插件逻辑必须做好时限控制，单次调用最长响应时间不得超过50秒(华为云WAF单次请求最少超时时间为60秒)。大数据量处理必须做好分页控制，单次查询请求（包含分录）不得超过1万条，保存请求不得超过2000条。
请求频次限制	公有云：每租户账套accountId最多600次/分，每个第三方应用客户端最多30次/秒。私有云：客户可按第三方应用、API URL配置限流规则，可参考公有云限流策略。