跳到主要内容

概念

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

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

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

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

URL​

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

  1. 对象列表:{{base_url}}/{app}/{model}/list/{level}/{sid}/{serializer}/
  2. 对象详情:{{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表示公司对象organizationsorganization
Personnel表示公司成员organizationspersonnel
Team表示公司的团队organizationsteam
Organization Widget表示公司中安装的小插件organizationsorganizationwidget
Statement表示月度报表organizationsstatement
Backup表示备份数据organizationsbackup
Workspace表示工作空间对象workspacesworkspace
Workspace Member表示工作空间成员或团队workspacesmember
Table表示表对象tablestable
Column表示表的列tablescolumn
Row表示表的行tablesrow
Cell表示行的单元格tablescell
Section表示行的章节tablessection
Version表示行的版本tablesversion
Filter表示表的筛选条件tablesfilter
Workflow表示表的工作流tablesworkflow
Step表示工作流的步骤tablesstep
Activity表示用户活动activitiesactivity
Widget表示小插件对象widgetswidget

层级​


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

  • organization: 返回公司层级内的结果。
  • user: 返回特定用户的结果(已弃用)。
  • workspace: 返回工作空间的结果(已弃用)。

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

列表 APIlevel=organizationlevel=userlevel=workspace
Organization List是是-
Organization Member List是--
Team List是是-
Organization Widget是--
Statement List是--
Backup List是--
Workspace List是是-
Workspace 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: 未授权用户

工作空间级别有三种角色:

  • Workspace Admin: 工作空间管理员
  • Workspace Edit: 在工作空间中拥有 edit 权限的成员
  • Workspace View: 在工作空间中拥有 view 权限的成员
APIGETPOSTPUTPATCHDELETE
公司列表Admin, MemberAdmin---
公司详情Admin, Member--Admin-
公司成员列表Admin, MemberAdmin---
公司成员详情Admin, Member--Admin-
团队列表Admin, MemberAdmin---
团队详情Admin, Member--AdminAdmin
公司小插件列表Admin, MemberAdmin--Admin
公司小插件详情Admin, Member---Admin
陈述列表Admin----
陈述详情Admin----
备份列表AdminAdmin---
备份详情Admin----
工作空间列表Admin, Workspace Admin, Workspace Edit, Workspace ViewAdmin---
工作空间详情Admin, Workspace Admin, Workspace Edit, Workspace View--Admin, Workspace Admin-
工作空间成员列表Admin, Workspace Admin, Workspace Edit, Workspace ViewAdmin, Workspace Admin---
工作空间成员详情Admin, Workspace Admin, Workspace Edit, Workspace View--Admin, Workspace AdminAdmin, Workspace Admin
表格列表Admin, MemberAdmin---
表格详情Admin, Member--Admin-
列列表Admin, MemberAdmin---
列详情Admin, Member--Admin-
过滤器列表Admin, MemberAdmin, Member---
过滤器详情Admin, Member--Admin, MemberAdmin, Member
行列表Admin, Workspace Admin, Workspace Edit, Workspace ViewWorkspace Admin, Workspace Edit-Workspace Admin, Workspace Edit-
行详情Admin, Workspace Admin, Workspace Edit, Workspace View--Workspace Admin, Workspace Edit-
单元格列表Admin, Workspace Admin, Workspace Edit, Workspace ViewWorkspace Admin, Workspace Edit---
单元格详情---Workspace Admin, Workspace Edit-
章节列表Admin, Workspace Admin, Workspace Edit, Workspace ViewWorkspace Admin, Workspace Edit---
章节详情Admin, Workspace Admin, Workspace Edit, Workspace View--Workspace Admin, Workspace Edit-
版本列表Admin, Workspace Admin, Workspace Edit, Workspace View----
版本详情Admin, Workspace Admin, Workspace Edit, Workspace 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)