上海交通大学开发者平台

# 概述

# 数据资源说明

  • 数据资源是指校内各类信息系统在建设、使用过程中产生和累积的各类数据。由数据产生部门保障数据的完整性、准确性、时效性和可用性；由数据产生部门或其管理部门确定数据的密级及共享方式。
  • 使用部门对从数据资源中获取的数据，只能按照申请时的使用用途用于本部门履行职责需要，不得直接或以改变数据形式等方式提供给第三方。

# 数据资源申请

申请API接口，请通过数据资源申请流程 (opens new window)完成申请。

# 数据资源API表述

  • 最新版数据资源API是基于restful风格API接口，易于理解，调用方便。根据用户申请资源时所申请的字段，实现字段级别权限控制。
  • 所有数据API接口使用统一的请求前缀（GET https://graphql.sjtu.edu.cn/v1），不同API接口，请求路径不同。

# 令牌获取

数据API采用上海交通大学的OAuth认证服务完成API权限校验，获取令牌授权使用客户端凭据授予（Client Credentials Grant），授权scope为exchange_data。

# 构造请求

  • 请求参数可以跟在API访问的资源路径之后，查询参数前面需要带一个"?"，形式为“参数名=参数取值”
  • access_token遵循oauth2标准，可以放在请求地址上，也可以放在header中

# 分页参数说明

  • first为分页查询起始位置，默认为1
  • offset为分页查询最大偏移量，默认每次查询offset最大为200
  • 假设每次获取100条数据，第一次：first=1&offset=100，第二次：first=101&offset=100

# 返回数据

# 状态码

HTTP响应状态代码指示特定HTTP请求是否已成功完成。状态代码由section 10 of RFC 2616 (opens new window)定义。在API响应中常见的状态码见下表。

状态码 描述
200 OK 请求成功
400 Bad Request 请求错误(通常是参数错误)
403 Forbidden 拒绝请求(通常是鉴权失败)
404 Not Found 请求资源未找到(通常是url地址错误)
405 Method Not Allowed 请求的方法不被允许(通常是请求方法错误)
503 Service Unavailable 服务不可用(通常是API服务器因维护正在重启中或者停机中)

# 数据格式

所有复杂对象的数据格式使用JSON表示。比如：

{
	"accountNo": "zhangsan",
	"guid": "28A42245-7435-499C-B2B7-xxxxxxx",
	"displayName": "张三",
	"accountStatus": "正常",
	"identityExpireDate": "2023-07-31",
	"userStyle": "faculty",
	"userId": "xxxxx",
	"cardType": "01",
	"cardNo": "31011119920311xxxx",
	"telephone": "",
	"email": "testprofile@sjtu.edu.cn",
	"topOrganizeId": "40100",
	"topOrganizeName": "网络信息中心",
	"timestamp": "2022-08-19 00:00:00",
	"relationList": [{
		"userStyle": "faculty",
		"userId": "xxxxx",
		"expireDate": "2023-07-31",
		"cardType": "01",
		"cardNo": "31011119920311xxxx",
		"topOrganizeId": "40100",
		"topOrganizeName": "网络信息中心"
	}]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 通用结构

API的返回值的通用结构包含：

参数名 类型 描述
errno int 错误代码，返回0表示调用成功.
entities object[] 成功返回数据
error string 可选，返回错误信息
total int 本次api接口返回的数据总数，通过分页查询时，可通过该参数来判断是否继续查询
示例 请求成功返回数据
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
	"errno": 0,
	"error": null,
	"total": 1,
	"entities": [{
		"accountNo": "zhangsan",
		"guid": "28A42245-7435-499C-B2B7-xxxxxxx",
		"displayName": "张三",
		"accountStatus": "正常",
		"identityExpireDate": "2023-07-31",
		"userStyle": "faculty",
		"userId": "xxxxx",
		"cardType": "01",
		"cardNo": "31011119920311xxxx",
		"telephone": "",
		"email": "testprofile@sjtu.edu.cn",
		"topOrganizeId": "40100",
		"topOrganizeName": "网络信息中心",
		"timestamp": "2022-08-19 00:00:00",
		"relationList": [{
			"userStyle": "faculty",
			"userId": "xxxxx",
			"expireDate": "2023-07-31",
			"cardType": "01",
			"cardNo": "31011119920311xxxx",
			"topOrganizeId": "40100",
			"topOrganizeName": "网络信息中心"
		}]
	}]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
示例 请求错误返回数据，当用户鉴权失败时，http响应状态码返回403
HTTP/1.1 403 OK
Content-Type: application/json;charset=UTF-8

{
  "errno": 1002,
  "error": "The interface has no access permission.",
  "total": []
  "total": 0
}
1
2
3
4
5
6
7
8
9

# 错误代码

API错误代码表

错误代码 错误名称 错误说明
0 成功
-1 API接口异常 未捕捉异常，可能数据库连接等因素导致
1000 请求API接口超时 规定时间接口未响应，将返回如下错误
1001 GRAPHQL解析错误 GraphQL语法错误
1002 权限验证失败 The interface has no access permission.
1003 系统内部异常 根据不同异常捕捉，返回相应错误信息
1004 API接口访问限制 针对部分设置API每日访问次数限制的，当超过访问次数，将返回如下错误

账号类APIs →