OpnForm项目REST API接口全面指南

概述

OpnForm提供了一个基于JWT认证的RESTful API接口，允许开发者通过编程方式管理工作区、表单和提交数据。本文将详细介绍API的基础知识、认证机制、使用限制以及错误处理等内容，帮助开发者快速上手使用OpnForm API。

API基础信息

基础URL

所有API请求都基于以下基础URL：

https://api.opnform.com

所有端点路径都是相对于这个基础URL的。

认证机制

OpnForm API采用JWT(JSON Web Token)进行认证，每个请求都必须在HTTP头中包含个人访问令牌：

Authorization: Bearer <access_token>

令牌权限

每个令牌都关联着一组权限(abilities/scopes)，这些权限限制了令牌可以执行的操作：

权限名称	权限描述
workspaces-read	读取用户所属的工作区
workspaces-write	创建、更新或删除工作区
workspace-users-read	列出工作区成员和邀请
workspace-users-write	管理工作区成员和邀请
forms-read	读取表单和提交数据
forms-write	创建或修改表单和提交数据

如果请求尝试执行超出令牌权限范围的操作，API将返回403 Forbidden错误。

分页机制

部分列表端点支持分页功能。开发者可以通过page查询参数(如?page=2)来获取后续页面的数据。

速率限制

为防止滥用API，OpnForm实施了速率限制：

• 每个IP地址每分钟最多允许100次请求
• 超过限制将返回429 Too Many Requests错误

错误处理

API使用标准HTTP状态码和JSON格式返回错误信息。典型的错误响应如下：

{
  "message": "验证失败",
  "errors": {
    "title": ["标题字段是必填项"]
  }
}

常见HTTP状态码及其含义：

状态码	含义
400	请求错误/验证失败
401	缺少或无效的令牌
403	令牌缺少所需权限
404	资源不存在
429	超过速率限制
500	服务器内部错误

快速开始示例

以下是一个简单的cURL命令示例，展示如何获取工作区列表：

curl -H "Authorization: Bearer <access_token>" https://api.opnform.com/open/workspaces

最佳实践建议

1. 令牌安全：妥善保管个人访问令牌，避免泄露
2. 错误处理：在代码中妥善处理各种可能的错误响应
3. 速率控制：合理控制请求频率，避免触发速率限制
4. 权限管理：根据实际需求申请最小必要权限的令牌

通过本文的介绍，开发者应该已经掌握了OpnForm API的基本使用方法。接下来可以根据具体需求，参考各端点的详细文档进行开发工作。