接口开发规范

概述

此文档为研学开放平台对外开放API接口的设计文档，文档内容包含开放API的设计原则，数据标准，认证方式。此文档的期望读者为研学开放平台的开发者。

设计原则

• 遵循 RESTful 设计原则
  使用合适的 HTTP 方法（GET、POST、PUT、DELETE 等），具体实现可遵循以下规则：

  • 识别资源和操作
  • 使用名词表示资源
  • 使用HTTP方法标识操作

  例如，对于获取用户信息的操作，传统的url路径可能是/getUsers，使用restful风格的请求，可以替换为使用 GET 方法来请求 /users/{userID} 路径，其中users 是资源，GET 方法是获取用户的操作，{userID} 是用户的唯一标识符。

  对于创建新用户的操作，可以使用 POST 方法来请求 /users 路径，向其中发送包含用户信息的请求体，其中users 是资源，POST 方法是新增用户的操作，

  对于更新用户信息的操作，可以使用 PUT 方法来请求 /users/{userID} 路径，其中 users 是资源，PUT 方法是更新用户的操作，{userID} 是要更新的用户的唯一标识符。

  对于删除用户的操作，可以使用 DELETE 方法来请求 /users/{userID} 路径，以删除特定用户，其中users 是资源，DELETE 方法是删除用户的操作，{userID} 是用户的唯一标识符。

• 使用清晰的资源命名
  通过 URI 表达资源的层级关系，例如，对于用户系统，可以使用以下 URI 来表达资源的层级关系：

  • /users: 所有用户的列表。
  • /users/{userID}: 特定用户的详细信息。
  • /users/{userID}/actions: 特定用户下的所有功能的业务数据。
  • /users/{userID}/actions/{actionID}: 特定用户下的特定功能的业务数据。

• 版本控制。

  在 API 的设计中应包含版本控制，可以通过在 URI 中添加版本号来实现，如 /v1/users、/v2/users 等。

注：以上示例接口路径仅供参考非真实功能接口路径

参数标准

• 请求头：目前开放平台中开放的接口都需要在请求头Header中携带Authorization字段作为认证的标识，Authorization的获取方式详见接口文档=>如何获取JWT (opens new window)

• 请求体：

  • 路径参数中注意敏感词加密；
  • 请求体参数，请使用json格式。

• 返回实体报文：

  {
  "success": true, //是否请求成果
      "message": "",   //返回消息提示
      "content": null, //返回数据
      "count": 10,     //返回数据条数，分页专用
      "total": 100,    //返回数据总条数，分页专用
      "code": 200      //请求成功返回状态码
  }
  

• 安全性：

  • 避免在URL中包含敏感信息，
  • 使用 HTTPS 协议确保数据传输的安全性。

• 常见异常返回码

  返回码	异常信息	中文提示
  400200	invalid_token	无效的Token!
  400201	invalid_scope	无效的作用域！
  400202	invalid_request	无效的请求！
  400203	invalid_client	无效的客户端！
  400204	invalid_grant	无效的授权！
  400205	redirect_uri_mismatch	请求路径无法正确匹配！
  400206	unauthorized_client	客户端认证无效！
  400207	expired_token	Token失效！
  400208	unsupported_grant_type	不支持的授权类型！
  400209	unsupported_response_type	不支持的响应类型！
  400212	unauthorized	认证失败，请重新登录！
  400213	signature_denied	不支持的签名类型！
  400430	access_denied	权限不足，拒绝访问！
  400431	access_denied_black_limited	IP或域名限制访问！
  400432	access_denied_white_limited	IP或域名不在白名单内，拒绝访问！
  400433	access_denied_authority_expired	授权已过期，拒绝访问！
  400434	access_denied_updating	正在升级维护中，请稍后再试！
  400435	access_denied_disabled	请求地址，禁止访问！
  400436	access_denied_not_open	请求地址，拒绝访问！
  400300	bad_credentials	账号或密码错误！
  400301	account_disabled	账号已被禁用！
  400302	account_expired	账号已过期！
  400303	credentials_expired	授权过期！
  400304	account_locked	账号已锁定！
  400305	username_not_found	账号不存在！
  400306	password_error	密码错误！
  400307	username_or_password_null	用户名或密码错误！
  400400	bad_request	无效的请求！
  400404	not_found	无效的访问地址！
  400405	method_not_allowed	请求方式不支持！
  400406	media_type_not_acceptable	媒体类型不支持！
  400429	too_many_requests	访问过于频繁，请稍后再试！
  400430	gateway_url_error	网关路由错误！
  400500	error	服务器繁忙，请稍后再试！
  400504	gateway_timeout	网关超时！
  400503	service_unavailable	服务暂时无法访问！