API设计：如何确保命令按特定顺序调用

Question

我们正在为我们制造的手持式传感器设计一个 API，以便我们的客户可以将其集成到他们的机器人上。

传感器上的功能要求用户完成一系列步骤才能获得最终结果。 当用户将我们的设备用作手持设备时，我们能够强制用户遵循此顺序，因为我们的 GUI 会引导他们完成每个步骤。然而，使用我们的 API 会有点困难，因为集成商可以不按特定顺序进行调用。 目前，我们依靠文档来确保 API 调用是按顺序进行的。

但是，我的问题是：这可以通过 API 来完成吗？

例如，我尝试了以下方法，但最终放弃了这种方法，因为我觉得它变得过于固执己见，最终无法执行。

用户向我们传感器的 API 发出以下请求

{
    "command": "do_step_one"
}

当传感器响应“完成”时，它会建议下一步和取消选项，如下所示：

{
    "respondingToCommand": "do_step_one",
    "date": "2023-04-03T19:23:23.000000",
    "message": "Successfully completed step one",
    "nextStep": [
     {
       "name": "Continue to step two",
       "command": "do_step_two"
     },
     {
       "name": "Cancel",
       "command": "cancel_sequential_process"
     },
    ],
    "status": "done"
}

Answer 1

对于这个简短的回答，我将忽略有关 API 设计的“严厉的爱”思想学派，在这种学派中，无视记录的做事方式的用户会得到他们得到的东西。考虑一个大客户，他找到了一种奇怪的方法来使某些东西正常工作，但你的下一个内部修复破坏了他们的工作流程 - “为什么我们要修复我们的代码，你是破坏它的人！”

您可以通过要求仅从先前响应中可用的资源来强制执行特定的请求顺序。作为一般示例，您的步骤可能是：

1. 登录，返回身份验证令牌
2. 使用身份验证令牌启动硬件会话，该令牌返回会话 ID
3. 使用会话 ID 列出可用传感器，这会返回传感器 ID 列表
4. 使用会话 ID 和传感器 ID 打开传感器电源，这会返回特定于会话的传感器句柄
5. 使用传感器手柄轮询传感器状态
6. 使用会话 ID 关闭会话

每个步骤都建立在之前的步骤之上。用户仍然有自由 – 例如，传感器 ID 在会话之间保持不变可能是有意义的，因此也许他们可以直接进入步骤 4，而无需执行步骤 3，并且只需重新使用他们从存储的传感器 ID上一届会议。

给定一个特定的目标，API 用户应该能够确定他们需要的先前步骤，而做到这一点的一个好方法是拥有关联的资源——即使它们只是证明他们已经完成了必备任务的 ID。

最好的 API 会引导您沿着花园小路走下去，而不是将您带入一片黑暗的树林，周围隐藏着捕熊器。