概念

Labii API 是一个 REST API，为 Labii 平台提供编程访问。它支持所有不同的调用方法，包括 GET、POST、PUT 和 DELETE。

Labii API 的设计目标是易于访问且灵活，允许开发人员使用他们选择的编程语言和工具与 Labii 平台进行交互。API 完全文档化，并提供有关每个端点的详细信息，包括 HTTP 方法、端点 URL、所需参数和预期响应。

Labii API 的一些关键特性包括：

基于资源的架构：Labii API 使用基于资源的架构，这意味着每个端点代表 Labii 平台中的一个特定资源，例如项目、实验或行。
认证和授权：Labii API 使用 OAuth 2.0 进行认证和授权，确保只有授权用户可以访问敏感数据。
分页和过滤：API 支持分页和过滤，允许开发人员根据各种标准检索特定的数据子集。

URL

Labii API 使用两种类型的 URL 来表示对象的两种不同视图：

对象列表：{{base_url}}/{app}/{model}/list/{level}/{sid}/{serializer}/
对象详情：{{base_url}}/{app}/{model}/detail/{sid}/

默认情况下，base_url 设置为 https://www.labii.dev/。如果您的组织拥有专用服务器，可以使用 https://[your subdomain].labii.dev/ 作为 base_url。

app 参数表示应用程序的名称，而 model 参数表示模型的名称。您可以在 Labii 文档中查看更多有关这些参数的详细信息。

level 参数表示要检索的记录范围。您可以在 Labii 文档的“层级”章节中查看更多有关此参数的详细信息。

sid 参数是一个静态且加密的 Labii 对象 ID。它必须与 level 参数匹配。例如，如果 level=organization，则 sid 参数必须是组织的 SID。

最后，serializer 参数表示返回数据字段的范围。有以下三种选项：

name: 仅返回对象的 SID 和名称，速度非常快。
list: 返回对象的选定字段，速度较快。
detail: 返回对象的所有字段，速度较慢。

对象

Labii API 提供各种对象，这些对象代表 Labii 平台中不同类型实体，每个对象都有一组用于与该实体交互的方法。以下是 Labii API 中可用对象的列表，包括它们的描述、所属的应用程序及其对应的模型：

名称	描述	应用	模型
Organization	表示组织对象	organizations	organization
Personnel	表示组织成员	organizations	personnel
Team	表示组织的团队	organizations	team
Organization Widget	表示组织中安装的小插件	organizations	organizationwidget
Statement	表示月度报表	organizations	statement
Backup	表示备份数据	organizations	backup
Project	表示项目对象	projects	project
Project Member	表示项目成员或团队	projects	member
Table	表示表对象	tables	table
Column	表示表的列	tables	column
Row	表示表的行	tables	row
Cell	表示行的单元格	tables	cell
Section	表示行的章节	tables	section
Version	表示行的版本	tables	version
Filter	表示表的筛选条件	tables	filter
Workflow	表示表的工作流	tables	workflow
Step	表示工作流的步骤	tables	step
Activity	表示用户活动	activities	activity
Widget	表示小插件对象	widgets	widget

层级

层级定义了要检索的记录范围。层级参数是列表 API 的必需参数。Labii 使用以下层级：

organization: 返回组织层级内的结果。
user: 返回特定用户的结果（已弃用）。
project: 返回项目的结果（已弃用）。

并非所有层级都适用于所有列表 API。如果使用了错误的层级，将返回 HTTP_406_NOT_ACCEPTABLE 错误。下表列出了每个 API 允许的所有层级。

列表 API	level=organization	level=user	level=project
Organization List	是	是	-
Organization Member List	是	-	-
Team List	是	是	-
Organization Widget	是	-	-
Statement List	是	-	-
Backup List	是	-	-
Project List	是	是	-
Project Member List	是	-	是
Table List	是	-	-
Column List	是	-	-
Filter List	是	是	-
Row List	是	是	是
Cell List	是	-	-
Section List	是	-	-
Version List	是	-	-
Activity	是	是	-
Widget	*	-	-

方法

以下文档描述了 Labii API 中使用的方法：

GET: 该方法用于获取一个或多个对象。
POST: 该方法用于创建一个对象。
PUT: 该方法用于更新一个对象。
PATCH: 该方法用于部分更新一个对象。
DELETE: 该方法用于删除一个对象。

不同角色在使用这些方法时具有不同的权限。组织级别共有五种角色：

Admin: 管理员
Member: 组织成员
Alumni: 已离开组织的成员
User: 不属于组织的其他 Labii 用户
Anonymous: 未授权用户

项目级别有三种角色：

Project Admin: 项目管理员
Project Edit: 在项目中拥有 edit 权限的成员
Project View: 在项目中拥有 view 权限的成员

API	GET	POST	PUT	PATCH	DELETE
组织列表	Admin, Member	Admin	-	-	-
组织详情	Admin, Member	-	-	Admin	-
组织成员列表	Admin, Member	Admin	-	-	-
组织成员详情	Admin, Member	-	-	Admin	-
团队列表	Admin, Member	Admin	-	-	-
团队详情	Admin, Member	-	-	Admin	Admin
组织小插件列表	Admin, Member	Admin	-	-	Admin
组织小插件详情	Admin, Member	-	-	-	Admin
陈述列表	Admin	-	-	-	-
陈述详情	Admin	-	-	-	-
备份列表	Admin	Admin	-	-	-
备份详情	Admin	-	-	-	-
项目列表	Admin, Project Admin, Project Edit, Project View	Admin	-	-	-
项目详情	Admin, Project Admin, Project Edit, Project View	-	-	Admin, Project Admin	-
项目成员列表	Admin, Project Admin, Project Edit, Project View	Admin, Project Admin	-	-	-
项目成员详情	Admin, Project Admin, Project Edit, Project View	-	-	Admin, Project Admin	Admin, Project Admin
表格列表	Admin, Member	Admin	-	-	-
表格详情	Admin, Member	-	-	Admin	-
列列表	Admin, Member	Admin	-	-	-
列详情	Admin, Member	-	-	Admin	-
过滤器列表	Admin, Member	Admin, Member	-	-	-
过滤器详情	Admin, Member	-	-	Admin, Member	Admin, Member
行列表	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	Project Admin, Project Edit	-
行详情	Admin, Project Admin, Project Edit, Project View	-	-	Project Admin, Project Edit	-
单元格列表	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	-	-
单元格详情	-	-	-	Project Admin, Project Edit	-
章节列表	Admin, Project Admin, Project Edit, Project View	Project Admin, Project Edit	-	-	-
章节详情	Admin, Project Admin, Project Edit, Project View	-	-	Project Admin, Project Edit	-
版本列表	Admin, Project Admin, Project Edit, Project View	-	-	-	-
版本详情	Admin, Project Admin, Project Edit, Project View	-	-	-	-
活动列表	Admin, Member	-	-	-	-
活动详情	-	-	-	-	-
小插件列表	Admin, Member	-	-	-	-
小插件详情	Admin, Member	-	-	-	-

序列化器

Labii API 中的序列化器用于将数据库中的数据转换为其他格式。Labii 中的每个序列化器代表一组不同的字段用于返回。Labii API 支持以下序列化器：

name: 该序列化器返回记录的 sid 和 name 字段。
list: 该序列化器返回一些基本字段。不同表格的字段集可能不同。
detail: 该序列化器返回一组完整的字段。

状态码

以下是 Labii API 使用的状态码列表：

HTTP_200_OK: API 调用成功时返回
HTTP_201_CREATED: 对象创建成功时返回
HTTP_204_NO_CONTENT: 对象成功删除时返回
HTTP_401_UNAUTHORIZED: 用户未认证时返回
HTTP_403_FORBIDDEN: 用户没有权限时返回
HTTP_406_NOT_ACCEPTABLE: 参数不正确时返回
HTTP_500_INTERNAL_SERVER_ERROR: 内部错误时返回

错误

以下是列表视图和详情视图中常见的错误。

列表视图

HTTP_401_UNAUTHORIZED - token 无效
HTTP_403_FORBIDDEN - 用户没有权限执行该操作
HTTP_406_NOT_ACCEPTABLE - 提供的参数不可接受
- Wrong level - 提供的 level 无效或不允许
- Wrong sid - 提供的 sid 无法解密或与任何记录不匹配
- Wrong field - 错误：字段 (xxx) 不允许！
- Wrong datatype - list，可接受的数据是 DICT。如果有多个数据集，请多次 POST。

详情视图

HTTP_401_UNAUTHORIZED - token 无效
HTTP_403_FORBIDDEN - 用户没有权限执行该操作
HTTP_406_NOT_ACCEPTABLE - 提供的参数不可接受
- Wrong sid - 提供的 sid 无法解密或与任何记录不匹配
- Wrong field - 错误：字段 (xxx) 无法更新！

示例

使用 curl 获取记录列表：

curl -X get https://www.labii.dev/tables/rows/list/organization/xxx/list/ -H "Authorization: Token xxxx"

在 Python 中：

import requests
headers = {
    "X-Forwarded-For": "batch",
    "Content-Type": "application/json",
    "Authorization": "Token %s" % token
}
requests.get(url="https://www.labii.dev/tables/rows/list/organization/xxx/list", headers=headers)

URL​

对象​

层级​

方法​

序列化器​

状态码​

错误​

列表视图​

详情视图​

示例​

URL

对象

层级

方法

序列化器

状态码

错误

列表视图

详情视图

示例