API设计

API演进:版本控制和兼容性

一旦我们的api成熟,Segment就会努力维持一个严格的协议来保证api的稳定性。

配置API通过路径前缀进行静态版本控制。当前版本,/ v1beta.,是稳定的,适合生产使用,但不是100%成熟。在2018年12月12日公开发布之后,我们将不会发布任何向后不兼容的破坏性更改。然而,我们可能会进一步发布API的新版本/ v1betax.发布或作为主要版本发布(例如/ v1)。

路径当前存在的原因/ v1beta.是为了表明该部门的产品模型正在发展,并且我们正在寻求开发人员关于如何最好地将该模型公开供公众使用、扩展和自动化的反馈。

因此,/ v1beta.是否可在三个月后以书面通知的形式弃用/ v1,我们应该决定在决赛中征地任何破坏/ v1释放。

我们始终积极寻求关于我们API的人体工程学和广度的反馈。如果您有关于如何改进他们的想法,您希望看到作为扩展/ v1beta.或考虑改变/ v1,不要犹豫保持联系

常用方法和字段

CONFIG API是一组REST API,用于管理段资源。主要部分资源是:

  • 个人访问令牌
  • 工作区
  • 来源
  • 目的地
  • 跟踪计划

您可以使用标准方法管理每个资源:

方法 HTTP映射
列表 得到
得到 得到
创造 帖子
更新 补丁
删除 删除

错误

错误 HTTP状态 代码 原因
无效的参数 400错误请求 3. 该请求包含无效的JSON或字段包含无效值
未经身份验证的 401年未经授权 16. 访问令牌丢失或无效
PermissionDenied 403年被禁止的 7 一个访问令牌创建、更新和删除方法需要作用域
未找到 404没有找到 5 找不到请求或资源。请求方法或路径不正确,或者该资源不存在于此工作空间中(有时是因为输入错误)。
已经存在 409冲突 6 资源(例如源)已经存在给定的名称
资源疲惫不堪 要求太多了 8 已耗尽60个请求/秒的速率限制
内部 500内部服务器错误 13. 段在处理请求时遇到错误
未实现的 501年没有实现 12. 不支持或不实现该方法
不可用 503服务不可用 14. 空气污染指数下降
上游连接错误
或在头文件之前断开/重置
503服务不可用 N/A URL无效,因此请求不能路由到上游API服务

分页

List方法被分页。请求采用可选的页大小参数,通常默认为10或100项。如果有更多页大小项,则响应包括next_page_token.字段。然后你可以提供这个aspage_token.参数设置为下一个列表请求。如果集合中没有其他项目,next_page_token.将是空的。

更新掩码

更新方法按照补丁语义。除了要更新的数据之外,该方法还需要一个明确的字段名称来更新。这消除了空值周围的所有歧义。

美元卷曲-X补丁\-H“授权:承担者ACCESS_TOKEN美元\-D.{“目的地”:{“启用”:真的,“update_mask”:{“路径”:["目的地。启用"]}}'“https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics”

请注意,指定一个没有值的更新路径将会把字段变成一个空值(例如" ",0,或false)。例如,这会导致启用错误的:

美元卷曲-X补丁\-H“授权:承担者ACCESS_TOKEN美元\-D.'{“destination”:{“update_mask”:{“paths”:[destancest.enabled“]}}'“https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics”

请注意,指定数据但没有路径不会更改字段值。例如,这没有效果:

美元卷曲-X补丁\-H“授权:承担者ACCESS_TOKEN美元\-D.'{"destination": {"enabled": true}'“https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics”

资源名

资源由我们的服务和API公开的命名实体,资源名称是其标识符。每个资源都有自己独特的资源名称,由资源本身的ID或SLUS和任何父资源的ID或SLUS组成。

所以给定的源资源可能看起来像:

工作区/ < customer-workspace-slug > /资源/ < customer-source-slug >

段API使用更少的方案URI用于资源名称。这使我们通常会遵循REST URL约定,并为我们的标识符提供机器和人类清晰的标准。

当资源是客户或分段的信息时,段在不透明ID上的“slugs”,并不太可能更改,例如来源和目的地。对于姓名可能经常更改的资源(例如跟踪计划),我们将在创建和使用完全限定的资源名称时自动为您自动使用前缀ID。

虽然完整的资源名类似于普通的url,但它们不是一回事。随着Segment API的发展,单个资源可能由不同的API版本、API协议或API网络端点公开。

最后更改:2020年6月09日



开始使用细分

细分是将网站和移动应用数据整合到300多个分析和增长工具的最简单方法。
或者
创建免费帐户