API Docs - HackMD

# API Docs ## README > 本文档用于AICoach前后端沟通API接口，具体格式在下方已经有示例。Markdown中\#数量表示标题等级。统一规定二级标题为**API所属大类**，三级标题为**API名称**，四级标题为**API的描述项**。 > > - 三级标题的API Name为建议名，非特殊情况不要修改方便他人使用。需要修改请注明 > - Parameters为前端向后端发起请求时的参数，如果表格内表述不清楚可以另起一个4级标题描述 > - Method为http请求类型 > - URL为接口的URL形式 > > **注意事项：请大家按照统一格式增加和修改,方便通过目录直接索引到具体的API。如果参与了某个API的工作请把自己添加到designer中方便沟通交流。同时文档提供了评论功能、可以直接在评论里讨论（view mode）。比如README这一段的右边就有一条评论** > ### 暂时开一个debug版的测试地址：**http://GCRAZCDL006:8000** [TOC] ## User Information ### getUserInfo | Parameters | Method | URL | |:------------:|:------:|:----------------:| | NULL | GET | /user/info | #### parameters http request #### returns if fail: ```json= { "msg": 'error message', "status": 503, "data": null } ``` if success: ```json= { "login_status": 'is_login'/'not_login', "user_name": 'monica', "user_id": 3, } ``` #### designer - Xin Kang ### getUserById | Parameters | Method | URL | |:------------:|:------:|:----------------:| | user_id(int) | GET | /user/\<int:id\> | #### Name 没有特殊情况可以不写这一项 #### parameters 如果需要，可以添加更详细的说明 #### returns ```json= { "name":"Bob", "age":21, "ability": { "label": ['属性1', '属性2', '属性3'], # 属性数目固定，可不为3 "score": [55, 40, 80] }, # 能力值 "score": { "x_data": ['2019-11-10', '2019-11-11', '2019-11-12', '2019-11-13', '2019-11-14', '2019-11-15', '2019-11-16'], # 时间戳 "y_data": [20, 30, 25, 40, 41, 45, 45] # 分数 }, # 用来画积分曲线 "nextProblemId":1 # 自动推荐下一个题目的ID } ``` #### designer - Hao Wang - Hanyue Tu - Zhikai Chen ### getScore | Parameters | Method | URL | |:------------:|:------:|:----------------:| | user_id(int) | GET | /user/\<int:id\>/score | #### parameters http request and user_id #### returns ```json= { "user_id":1, "score":99, "msg": 'success' } ``` #### designer - Zhikai Chen ### getAbility | Parameters | Method | URL | |:------------:|:------:|:----------------:| | user_id(int) | GET | /user/\<int:id\>/ability | #### parameters http request and user_id #### returns ```json= { "user_id":1 , "ability": [51,34,65,97,84], # ability1, ability2, ability3, ability4, ability5 "msg": 'success' } ``` #### designer - Zhikai Chen ## Login/Logout/Register ### login | Parameters | Method | URL | |:------------:|:------:|:----------------:| | NULL | POST | user/login | #### parameters http request with body ```json= { "username": 'Joey' , "password": '123456' } ``` #### returns if fail: ```json= { "msg": 'error message', "status": 503, "data": null } ``` if success: ```json= { "msg": 'success', "status": 200, "data": {"user_name": 'Joey', "user_id": 1} } ``` #### designer - Xin Kang ### logout | Parameters | Method | URL | |:------------:|:------:|:----------------:| | NULL | NULL | user/logout | #### parameters http request #### returns ```json= { "msg": 'success', "status": 200 } ``` #### designer - Xin Kang ### register | Parameters | Method | URL | |:------------:|:------:|:----------------:| | NULL | POST | user/register | #### parameters http request with body ```json= { "username": 'Joey' , "password1": '123456', "password2": '123456', "email": 'test@exampe.com', } ``` #### returns if fail: ```json= { "msg": 'error message', "status": 503, "data": null } ``` if success: ```json= { "msg": 'success', "status": 200, "data": {"user_name": 'Joey', "user_id": 1} } ``` #### designer - Xin Kang ## Questionnaire Infomation ### getQuestionnaire | Parameters | Method | URL | |:------------:|:------:|:----------------:| | NULL | GET | user/\<int:id\>/questionnaire | #### Name 没有特殊情况可以不写这一项 #### parameters 如果需要，可以添加更详细的说明 #### returns ```json= { "items": [ { "question_id": 1, "type" : "single", # 单选或多选等，如只有单选可忽略这一项 "question": "问题1", "options": ["问题1的选项1", "问题1的选项2", "问题1的选项3", "问题1的选项4"] }, { "question_id": 2 "type": "single", # 单选或多选等，如只有单选可忽略这一项 "question": "问题2", "options": ["问题2的选项1", "问题2的选项2", "问题2的选项3"] } ] "msg": "success" # 获取成功的标志，若失败则会返回错误信息 } ``` #### designer - Hanyue Tu - Zhikai Chen ### postSurvey | Parameters | Method | url | |:------------:|:------:|:----------------:| |Json Data| POST|/user/\<int:id\>/questionnaire/submit/ #### Name 没有特殊情况可以不写这一项 #### json data ```json= { "user_id":1, "items": [ { "questionnaire_id" : 1, "submission": [1,2] # 如多选选择了选项1和2 }, { "questionnaire_id" : 2, "submission": [1] # 如单选选择了选项1 } ] } ``` #### returns #### designer - Hanyue Tu - Zhikai Chen ## Submission History Information ### getSubmissionById | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | getSubmissionById | submission_id(int) | GET | /user/\<int:user_id\>/submissionid/?submission_id=\<id\> | ```json= { "msg": "success", "submission_id": 1, "challenge_id": 1001, "data":{ "code": `def bubbleSort(arr): n = len(arr) # Traverse through all array elements for i in range(n): # Last i elements are already in place for j in range(0, n-i-1): # traverse the array from 0 to n-i-1 # Swap if the element found is greater # than the next element if arr[j] > arr[j+1] : arr[j], arr[j+1] = arr[j+1], arr[j] # Driver code to test above arr = [64, 34, 25, 12, 22, 11, 90] bubbleSort(arr) print ("Sorted array is:") for i in range(len(arr)): print ("%d" %arr[i]),` "editableLines"： [ [ 2, 2 ], # start_line and end_line [ 15, 17] ] #可编辑的行 "status": "pass", "stdin": "", "stdout": "", "sdterr": "", "comment": "this is hard" } } ``` ### getSubmissionList | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | getSubmissionList | user_id(int) | GET | /user/\<int:user_id\>/submission/?challenge_id=1001 | ```json= { "msg": "success", "data":[ { "submission_id": 1, "status": "pass", "comment": "this is hard" }, { "submission_id": 2, "status": "fail", "comment": null # 没有评论就为 null } ] } ``` ### postComment | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | commentSubmission | user_id(int) | POST | /user/\<int:user_id\>/comment/ | #### Input ```json= { "submission_id": 1, "data": "This is hard" } ``` #### Output ## Challenge Information ### rateChallenge | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | rateChallenge | user_id(int) | POST | /user/\<int:user_id\>/rate/ | #### Input ```json= { "user_id":1, "challenge_id":1001 "data": 9.5 /*0~10/* } ``` #### Output ### getChallengeById | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | getChallengeById | challenge_id(int) | GET | /user/\<int:user_id\>/challenge/?challenge_id=1001 | ```json= { "msg": "success" "challenge_id":1001, "data":{ "rate": Number or null, "title":"Challenge 1", "description":"The description of this challenge", ## "level": 1, # 难度值、比如1，2，3对应easy、normal、hard 模型组不提供暂此标签 "code": `def bubbleSort(arr): n = len(arr) # Traverse through all array elements for i in range(n): # Last i elements are already in place for j in range(0, n-i-1): # traverse the array from 0 to n-i-1 # Swap if the element found is greater # than the next element if arr[j] > arr[j+1] : arr[j], arr[j+1] = arr[j+1], arr[j] # Driver code to test above arr = [64, 34, 25, 12, 22, 11, 90] bubbleSort(arr) print ("Sorted array is:") for i in range(len(arr)): print ("%d" %arr[i]),` #返回整个题目就行(空行或换行为换行符即可) "editableLines"： [ (2, 2, "str1"), # start_line, end_line and guide (15, 17, "str2") ] #可编辑的行 "tags": ["tag1", "tag2"] #标签 } } ``` #### Name 没有特殊情况可以不写这一项 #### parameters challenge_id通过传统request.GET.get方式获取，需要在请求的query params中设置好 user_id设置为1就行，目前数据库只有一个用户 #### designer - Hao Wang - Zhikai Chen - Jingwei Yi ### submitChallenge | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | submitChallenge | user_id,challege_id | POST | /user/\<int:uid\>/submit/ | #### Input ```json= { "challenge_id": 12, "code": "..." } ``` #### Output ```json= { "msg": "success", "code": 200, /*状态码 200，201，404，500*/ "data": { "submission_id": 1, "status": "pass", "stdin": [ "1 2\n3 4", /* 第一组输入 */ "5 6\n7 8" /* 第二组输入 */ ], "userout": [ "3\n7", /* 第一组输出； */ "except Exception as e:\n^"/* 第二组输出 */ ], "stdout": [ "3\n7", /* 第一组输出； */ "11\n15" ], "hints": [ {...}, {...} ] } } ```  ## Recommendation System ### getRecomendation | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | getRecomendation | user_id(int) | GET | /user/\<int:id\>/recommend | ```json= { "msg":"success", "data":[challenge_id1,challenge_id2,challenge_id3...] # 推荐的题号 } ``` #### Name 没有特殊情况可以不写这一项 #### parameters 推荐系统返回推荐的题号，前端可以显示给用户，比如以题目列表高亮等形式，用户选择题目之后要重新调用getChallengeById接口获取推荐的题目内容 #### designer - Zhikai Chen  ## Action Record ### postClick | API Name | Parameters | Method | URL | |:-----------:|:------------:|:------:|:--------:| | postUserEvent | user_id(int),challenge_id(int) | POST | /user/\<int:id\>/click/ | ```json= { "user_id":1, "challenge_id":1001, "event": "click", # 必须是click字符 } ``` #### return #### description 此接口记录用户的每个预定义动作，用户进行这五种动作时一定要post这个请求给后端记录下来。click表示用户点击了这道题，rate表示用户对这道题进行了评分（data中存分数），pass和fail代表用户这道题run后的结果（data中也可以存用户评论） #### designer - Zhikai Chen

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.