快速入门

行者API 开放平台快速入门

行者目前已有超过3000万骑行用户，每天都有数十万条运动数据上传到云端。我们通过开放API为开发者和第三方客户端提供创新的硬件接入和数据访问，提升骑行用户的使用体验。

行者 API V1 是一个公开可用的接口，允许开发人员访问行者数据， 界面兼容行者APP。

如果您违反 API 协议，行者 保留撤销您的 API token的权利，包括但不限于用于支持虚拟竞赛，用于复制 行者 网站、服务或产品的用途，用于从事违法相关国家法律法规的行为。

🌈 功能目录

• 行者API 开放平台快速入门
  • 🌈 功能目录
  • 🚴 行者API简介 🏃
  • 🏄 如何创建开发者账号 🧗
  • 🏌 如何获取硬件设备数据 📱
    • 前提条件
    • 登录 https://www.imxingzhe.com/home/#/developer/mydevices/ 网址, 页面如下：
    • 页面名词解释
    • 图表解释 📈
  • 🧗🏿‍️ 如何使用OAuth 2.0授权 🏊
  • 🔨 如何构建请求的开发细节 🤺
    • 准备工作
    • Web 应用
      • cURL 请求如下:
      • Response内容
      • Example cURL Request
  • 🏊 如何使用Swagger 🏄
  • ⛵ 如何获取开发支持 🚴

🚴 行者API简介 🏃

行者 REST API，提供基于行者账号的授权，个人信息，轨迹，路线等数据的访问。目前接口免费使用，要获取用户数据，您必须提出申请并请求用户使用 行者账号授权登录，并使用 OAuth 2.0 授予您的应用程序某些权限。

行者 API 的每个应用程序都将受到限制。 默认速率限制允许每 15 分钟 1000 个请求，每天最多 6,0000 个请求。如果您需要更多的请求次数，请联系我

🏄 如何创建开发者账号 🧗

首先，我们需要注册一个行者账号，然后创建一个第三方应用。

1. 如果还没有行者账号，请前往 https://www.imxingzhe.com/user/register 注册账号
2. 注册成功后，登录 https://www.imxingzhe.com/home/#/settings/api 创建一个应用
3. 您可以看到 “我的应用” 页面，页面需要填写的内容如下：
   • 名称： 应用的名称
   • 类型： APP应用的类型
   • ID： 行者官方给颁发的应用ID
   • 秘钥： 行者官方给颁发的应用秘钥（请妥善保密保管秘钥）
   • Authorization token： Oauth2与行者交互使用的授权令牌（请妥善保密保管）
   • Refresh token： 刷新令牌可以获取一个新的授权令牌（请妥善保密保管）
   • 请求配额：当前应用请求行者API的配额
   • 授权回调域名：When building your app, change “Authorization Callback Domain” to localhost or any domain. When taking your app live, change “Authorization Callback Domain” to a real domain.

创建页面如下图：

更新页面如下图：

🏌 如何获取硬件设备数据 📱

前提条件

• [] 已经注册第三方应用, Oauth2授权成功
• [] 已经申请行者官方绑定设备模型, 请联系行者官方
• [] 硬件设备已成功绑定到行者平台

登录 https://www.imxingzhe.com/home/#/developer/mydevices/ 网址, 页面如下：

页面名词解释

• 设备可用授权数： 与行者官方签订的可用设备总数量
• 总计激活数量： 厂商旗下所有设备模型已激活的数量

图表解释 📈

当前支持选择一种设备模型和年份，可以查看该年份下设备模型 每月 的统计数据

• 激活数量：设备在行者平台注册成功的设备数量
• 活跃数量：设备访问行者平台成功的设备数量

🧗🏿‍️ 如何使用OAuth 2.0授权 🏊

目前行者第三方应用的认证是通过 OAuth 2.0协议。开发者创建第三方应用后， 用户通过OAuth行者授权第三方访问行者的数据。在整个交互过程中，行者不会储存任何敏感信息，下面文档将带领开发者一步一步接入到行者中。

当 OAuth 在初始化时，用户会被提醒登录到行者网站并授权访问。在浏览器中会出现如下画面：

整个 OAuth2.0 的授权流程如下：

🔨 如何构建请求的开发细节 🤺

准备工作

创建APP成功，并且妥善保管 APP 的客户端ID和客户端秘钥。如下图，分别为 client_id 和 client_secret

Web 应用

1. Redirect the user to GET https://www.imxingzhe.com/oauth2/v2/authorize . 填入参数 构建重定向url 填入 client_id 构建如下url: https://www.imxingzhe.com/oauth2/v2/authorize?client_id=bc38eba7a81d2faa1361&response_type=code&state=abc&scope=read 参数解释, 将下列变量替换为开发者自己APP的参数:

   client_id: 上图中的 客户ID

   response_type: code 固定值对应oauth2中的 authorize type

   state: 用户自定义变量，行者会在回调是将该值返回

   scope: read 或 write ， read 只会读取行者数据，write 允许用户上传数据到行者

   redirect_uri: 授权回调地址, 接收 code 参数以及 state

2. 用户点击授权后，行者服务器将跳转到用户填写的 redirect_uri 中并在 query_string 携带 state 和 code 参数 如下所示 https://www.redirect-uri-to-your-app.com/accept/oauth2_code/?state=string&code=xxxx

3. 获取code, 使用code以及其他参数，访问 access_token 接口，获取access_token等授权数据

   注意: request 的 content-type: multipart/form-data

   cURL 请求如下:

   curl --location 'https://www.imxingzhe.com/oauth2/v2/access_token/' \
   --header 'Authorization: Bearer bc38eba7a81d2faa1361:e9337e008a9833040b3d07287db12f39a2bbcd6c' \
   --header 'Cookie: sessionid=fmjvuq6mkbxeo703o9678473dopm56ye' \
   --form 'code="code"' \
   --form 'grant_type="authorization_code"'

   Response内容

   {
     "token_type": "Bearer",
     "expires_at": 1568775134,
     "expires_in": 21600,
     "refresh_token": "e5n567567...",
     "access_token": "a4b945687g..."
   }

4. 使用 token 访问 行者 OpenAPI 在访问行者 OpenAPI 所有 resource 时，需要在请求中构建 header 如下： Authorization: Bearer #{access_token}

   Example cURL Request

   curl -G https://www.imxingzhe.com/openapi/v1/athlete/info/ -H "Authorization: Bearer ReplaceWithAccessToken"

5. 解绑 POST https://www.imxingzhe.com/oauth2/v2/deauthorize

🏊 如何使用Swagger 🏄

通过OAuth2.0授权协议之后，需要熟悉行者的OpenAPI。 行者提供了swagger交互式接口网站，可以便捷的开发，调试 API。

1. 登录行者网站，且创建了第三方APP应用
2. 登录 https://www.imxingzhe.com/openapi/doc/ 网站

请求相关内容 Authentication

API相关页面

⛵ 如何获取开发支持 🚴

---