From afe3e2969dce2792e8df5486a81573398cb5f1f1 Mon Sep 17 00:00:00 2001 From: IDzyre Date: Tue, 9 Apr 2024 19:36:28 -0700 Subject: [PATCH 1/4] Add student API documentation --- source/index.html.md | 2 + source/student_api/index.html.md | 233 +++++++++++++++++++++++++++++ source/stylesheets/screen.css.scss | 14 +- 3 files changed, 240 insertions(+), 9 deletions(-) create mode 100644 source/student_api/index.html.md diff --git a/source/index.html.md b/source/index.html.md index 9e7f5e6..f4d4faf 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -16,6 +16,8 @@ search: true *Note: API is still a work in progress.* +For the students, view the student api + API provides an alternative way of interacting with Submitty. It facilitates testing, helps system administrators to modify resources and enables users to create customized frontends. Note that as we rely on the Authorization header information to authenticate users, please make sure that you have a correct Apache configuration file as specified in [Installation Version Notes: v19.06.02](https://submitty.org/sysadmin/version_notes/v19.06.02). diff --git a/source/student_api/index.html.md b/source/student_api/index.html.md new file mode 100644 index 0000000..c7c7560 --- /dev/null +++ b/source/student_api/index.html.md @@ -0,0 +1,233 @@ +--- +title: Submitty API Reference + +language_tabs: # must be one of https://git.io/vQNgJ + - shell + +toc_footers: + - Documentation Powered by Slate + +includes: + +search: true +--- + +# Introduction + +*Note: Student API is still a work in progress.* + +API provides an alternative way of interacting with Submitty. This is intended for students to be able to interact with Submitty without using the web UI. + +__*Note: All student requests require a parameter of 'user_id' for verification.*__ + + + +# Requests + +Submitty supports requests using the following two `content-types`: + +* application/json +* application/x-www-form-urlencoded + +while anything involving files should use: + +* multipart/form-data + +All endpoints use the `/student_api` path off the base Submitty URL, followed by the specific endpoint +for the API in question. + +# Responses + +> Example of a `success` JSON response: + +```json +{ + "status": "success", + "data": null +} +``` + +> Example of a `fail` JSON response: + +```json +{ + "status": "fail", + "message": "Gradeable does not exist." +} +``` + +All API responses will be returned as `application/json` and conform to a modified +version of the [JSend specification](https://labs.omniti.com/labs/jsend). A response +returned from the server is expected to be one of the following three response types. + +| Type | Description | Required Keys | Optional Keys | +|---------|-----------------------------------------------------------------------------------------------------|----------------|---------------| +| success | All went well, and (usually) some data was returned | status, data | | +| fail | There was a problem with the data submitted, or some pre-condition of the API call wasn't satisfied | status, message | data | +| error | An error occurred in processing the request, i.e. an exception was thrown | status, message | data, code | + +# Authentication + +```shell +# With shell, you can just pass the correct header with each request +curl "student_api_endpoint_here" + -H "Authorization: my_token" +``` + +> Make sure to replace `my_token` with your API token, or the API will return JSON like this: + +```json +{ + "status": "fail", + "message": "Unauthenticated access. Please log in." +} +``` + +Submitty uses [JSON Web Tokens](https://jwt.io/) to allow access to the API. You can obtain your API token through the following endpoint. + +Kittn expects for the API token to be included in all API requests to the server in a header that looks like the following: + +`Authorization: my_token` + + + +## Get Token + +```shell +curl -X POST \ + /student_api/token \ + -F user_id=student \ + -F password=student +``` + +> The above command returns JSON structured like this: + +```json +{ + "status": "success", + "data": { + "token": "a long string" + } +} +``` + +Note that every time you request a new token, the previous token will be invalidated. + +### HTTP Request + +`POST /student_api/token` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID +password | User's password + +## Invalidate Token + +```shell +curl -X POST \ + /student_api/token/invalidate \ + -F user_id=student \ + -F password=student +``` + +The endpoint invalidates the token you requested before. + +### HTTP Request + +`POST /student_api/token/invalidate` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID +password | User's password + +# Gradeables + +## Get score + +```shell +curl -X GET \ + /student_api///gradeable//score?user_id= + +``` +> Possible responses: + +```json +{ + "status": "success", + "data": { + "score": 0 + } +} +``` +```json +{ + "status": "fail", + "message": "Gradeable does not exist" +} +``` + +The endpoint returns the score of an autograded gradeable. + +### HTTP Request + +`GET /student_api///gradeable//score?user_id=` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID + +## Submit VCS Gradeable + +```shell +curl -X POST \ + /student_api///gradeable//upload\ + -F user_id=student \ + -F vcs_checkout=true +``` +> Possible responses: + +```json +{ + "status": "success", + "data": "Successfully uploaded version {#} for {Gradeable Title}" +} +``` +```json +{ + "status": "fail", + "message": "Invalid gradeable id '{Gradeable ID}'" +} +``` +```json +{ + "status": "fail", + "message": "Student API for upload only supports VCS gradeables" +} +``` + + +The endpoint requests for a VCS gradeable to be submitted. + +### HTTP Request + +`GET /student_api///gradeable//upload` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID + diff --git a/source/stylesheets/screen.css.scss b/source/stylesheets/screen.css.scss index ed23b31..cd9b594 100644 --- a/source/stylesheets/screen.css.scss +++ b/source/stylesheets/screen.css.scss @@ -2,7 +2,7 @@ @import 'normalize'; @import 'variables'; @import 'icon-font'; -// @import 'rtl'; // uncomment to switch to RTL format +/*@import 'rtl'; // uncomment to switch to RTL format*/ /* Copyright 2008-2013 Concur Technologies, Inc. @@ -33,7 +33,7 @@ html, body { @extend %default-font; background-color: $main-bg; height: 100%; - -webkit-text-size-adjust: none; /* Never autoresize text */ + -webkit-text-size-adjust: none; } //////////////////////////////////////////////////////////////////////////////// @@ -62,7 +62,6 @@ html, body { font-size: 13px; font-weight: bold; - // language selector for mobile devices .lang-selector { display: none; a { @@ -71,7 +70,6 @@ html, body { } } - // This is the logo at the top of the ToC .logo { display: block; max-width: 100%; @@ -91,7 +89,7 @@ html, body { width: $nav-width - ($nav-padding*2); outline: none; color: $nav-text; - border-radius: 0; /* ios has a default border radius */ + border-radius: 0; } &:before { @@ -220,7 +218,7 @@ html, body { transform: rotate(-90deg) translate(-100%, 0); border-radius: 0 0 0 5px; } - padding: 0 1.5em 5em 0; // increase touch size area + padding: 0 1.5em 5em 0; display: none; position: fixed; top: 0; @@ -254,7 +252,7 @@ html, body { background-color: $main-bg; min-height: 100%; - padding-bottom: 1px; // prevent margin overflow + padding-bottom: 1px; // The dark box is what gives the code samples their dark background. // It sits essentially under the actual content block, which has a @@ -314,9 +312,7 @@ html, body { // This is all the stuff with the light background in the left half of the page .content { - // fixes webkit rendering bug for some: see #538 -webkit-transform: translateZ(0); - // to place content above the dark box position: relative; z-index: 30; From 4453e9a0b451a7f8047e08c00e4ab85bd8daf361 Mon Sep 17 00:00:00 2001 From: IDzyre Date: Fri, 26 Apr 2024 20:01:21 -0700 Subject: [PATCH 2/4] Add documentation --- source/index.html.md | 122 +++++++++++++--- source/student_api/index.html.md | 233 ------------------------------- 2 files changed, 106 insertions(+), 249 deletions(-) delete mode 100644 source/student_api/index.html.md diff --git a/source/index.html.md b/source/index.html.md index f4d4faf..ff5f312 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -16,8 +16,7 @@ search: true *Note: API is still a work in progress.* -For the students, view the student api - +Most of the API is restricted to faculty, however the [Gradeables](#gradeables) section can be used by students or faculty. API provides an alternative way of interacting with Submitty. It facilitates testing, helps system administrators to modify resources and enables users to create customized frontends. Note that as we rely on the Authorization header information to authenticate users, please make sure that you have a correct Apache configuration file as specified in [Installation Version Notes: v19.06.02](https://submitty.org/sysadmin/version_notes/v19.06.02). @@ -171,18 +170,18 @@ curl --request GET \ "data": { "unarchived_courses": [ { - "semester": "f19", + "term": "f19", "title": "blank", "display_name": "", - "display_semester": "Fall 2019" + "display_term": "Fall 2019" } ], "archived_courses": [ { - "semester": "f19", + "term": "f19", "title": "sample", "display_name": "", - "display_semester": "Fall 2019" + "display_term": "Fall 2019" } ] } @@ -200,10 +199,10 @@ Get all the courses the user is taking or have taken. ```shell curl --request POST \ --url /api/courses \ - --form course_semester=f19 \ + --form course_term=f19 \ --form course_title=api \ --form head_instructor=instructor \ - --form base_course_semester=f19 \ + --form base_course_term=f19 \ --form base_course_title=sample \ --header 'Authorization: my_token' ``` @@ -220,10 +219,10 @@ Note that the endpoint builds a course based on a prior course offering (called Parameter | Description --------- | ----------- -course_semester | Semester of the new course +course_term | term of the new course course_title | Title (or code) of the new course head_instructor | Head instructor of the new course -base_course_semester | Semester of the base course +base_course_term | term of the base course base_course_title | Title (or code) of the base course # Courses.Users @@ -232,7 +231,7 @@ base_course_title | Title (or code) of the base course ```shell curl --request GET \ - --url /api///users \ + --url /api///users \ --header 'Authorization: my_token' ``` @@ -268,13 +267,13 @@ This end point gets all users in a course. ### HTTP Request -`GET /api///users` +`GET /api///users` ## Get Graders ```shell curl --request GET \ - --url /api///graders \ + --url /api///graders \ --header 'Authorization: my_token' ``` @@ -308,7 +307,7 @@ curl --request GET \ ### HTTP Request -`GET /api///graders` +`GET /api///graders` # Courses.Reports @@ -316,7 +315,7 @@ curl --request GET \ ```shell curl --request POST \ - --url /api///reports/summaries \ + --url /api///reports/summaries \ --header 'Authorization: my_token' ``` @@ -324,4 +323,95 @@ This endpoint helps system administrators set up cron jobs for automatic grade s ### HTTP Request -`POST /api///reports/summaries` +`POST /api///reports/summaries` + + +# Gradeables +## Get gradeable values + +```shell +curl -X GET \ + /api///gradeable//values?user_id= + +``` +> Possible response examples: + +```json +{ + "status": "success", + "data": { + "is_queued": false, + "queue_position": 3, + "is_grading": false, + "has_submission": true, + "autograding_complete": true, + "has_active_version": true, + "highest_version": 1, + "total_points": 0, + "total_percent": 0 + } +} +``` +```json +{ + "status": "fail", + "message": "Gradeable does not exist" +} +``` + +The endpoint returns values associated with an autograded gradeable with the given gradeable_id, which allows for determining a score on an assignment, if it has been graded, etc. + +### HTTP Request + +`GET /api///gradeable//values?user_id=` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID + +## Submit VCS Gradeable + +```shell +curl -X POST \ + /api///gradeable//upload\ + -F user_id=student \ + -F vcs_checkout=true \ + -F git_repo_id=true +``` +> Possible responses: + +```json +{ + "status": "success", + "data": "Successfully uploaded version {#} for {Gradeable Title}" +} +``` +```json +{ + "status": "fail", + "message": "Invalid gradeable id '{Gradeable ID}'" +} +``` +```json +{ + "status": "fail", + "message": "Student API for upload only supports VCS gradeables" +} +``` + + +The endpoint requests for a VCS gradeable with the given gradeable_id to be submitted. + +### HTTP Request + +`POST /api///gradeable//upload` + +### Parameters + +Parameter | Description +--------- | ----------- +user_id | User's unique ID +vcs_checkout | Required to be `true` +git_repo_id | Required value, however no specific value is checked. diff --git a/source/student_api/index.html.md b/source/student_api/index.html.md deleted file mode 100644 index c7c7560..0000000 --- a/source/student_api/index.html.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Submitty API Reference - -language_tabs: # must be one of https://git.io/vQNgJ - - shell - -toc_footers: - - Documentation Powered by Slate - -includes: - -search: true ---- - -# Introduction - -*Note: Student API is still a work in progress.* - -API provides an alternative way of interacting with Submitty. This is intended for students to be able to interact with Submitty without using the web UI. - -__*Note: All student requests require a parameter of 'user_id' for verification.*__ - - - -# Requests - -Submitty supports requests using the following two `content-types`: - -* application/json -* application/x-www-form-urlencoded - -while anything involving files should use: - -* multipart/form-data - -All endpoints use the `/student_api` path off the base Submitty URL, followed by the specific endpoint -for the API in question. - -# Responses - -> Example of a `success` JSON response: - -```json -{ - "status": "success", - "data": null -} -``` - -> Example of a `fail` JSON response: - -```json -{ - "status": "fail", - "message": "Gradeable does not exist." -} -``` - -All API responses will be returned as `application/json` and conform to a modified -version of the [JSend specification](https://labs.omniti.com/labs/jsend). A response -returned from the server is expected to be one of the following three response types. - -| Type | Description | Required Keys | Optional Keys | -|---------|-----------------------------------------------------------------------------------------------------|----------------|---------------| -| success | All went well, and (usually) some data was returned | status, data | | -| fail | There was a problem with the data submitted, or some pre-condition of the API call wasn't satisfied | status, message | data | -| error | An error occurred in processing the request, i.e. an exception was thrown | status, message | data, code | - -# Authentication - -```shell -# With shell, you can just pass the correct header with each request -curl "student_api_endpoint_here" - -H "Authorization: my_token" -``` - -> Make sure to replace `my_token` with your API token, or the API will return JSON like this: - -```json -{ - "status": "fail", - "message": "Unauthenticated access. Please log in." -} -``` - -Submitty uses [JSON Web Tokens](https://jwt.io/) to allow access to the API. You can obtain your API token through the following endpoint. - -Kittn expects for the API token to be included in all API requests to the server in a header that looks like the following: - -`Authorization: my_token` - - - -## Get Token - -```shell -curl -X POST \ - /student_api/token \ - -F user_id=student \ - -F password=student -``` - -> The above command returns JSON structured like this: - -```json -{ - "status": "success", - "data": { - "token": "a long string" - } -} -``` - -Note that every time you request a new token, the previous token will be invalidated. - -### HTTP Request - -`POST /student_api/token` - -### Parameters - -Parameter | Description ---------- | ----------- -user_id | User's unique ID -password | User's password - -## Invalidate Token - -```shell -curl -X POST \ - /student_api/token/invalidate \ - -F user_id=student \ - -F password=student -``` - -The endpoint invalidates the token you requested before. - -### HTTP Request - -`POST /student_api/token/invalidate` - -### Parameters - -Parameter | Description ---------- | ----------- -user_id | User's unique ID -password | User's password - -# Gradeables - -## Get score - -```shell -curl -X GET \ - /student_api///gradeable//score?user_id= - -``` -> Possible responses: - -```json -{ - "status": "success", - "data": { - "score": 0 - } -} -``` -```json -{ - "status": "fail", - "message": "Gradeable does not exist" -} -``` - -The endpoint returns the score of an autograded gradeable. - -### HTTP Request - -`GET /student_api///gradeable//score?user_id=` - -### Parameters - -Parameter | Description ---------- | ----------- -user_id | User's unique ID - -## Submit VCS Gradeable - -```shell -curl -X POST \ - /student_api///gradeable//upload\ - -F user_id=student \ - -F vcs_checkout=true -``` -> Possible responses: - -```json -{ - "status": "success", - "data": "Successfully uploaded version {#} for {Gradeable Title}" -} -``` -```json -{ - "status": "fail", - "message": "Invalid gradeable id '{Gradeable ID}'" -} -``` -```json -{ - "status": "fail", - "message": "Student API for upload only supports VCS gradeables" -} -``` - - -The endpoint requests for a VCS gradeable to be submitted. - -### HTTP Request - -`GET /student_api///gradeable//upload` - -### Parameters - -Parameter | Description ---------- | ----------- -user_id | User's unique ID - From e8b91ffafd39c448771d0d7affbef22253eea984 Mon Sep 17 00:00:00 2001 From: IDzyre Date: Tue, 30 Apr 2024 09:49:58 -0700 Subject: [PATCH 3/4] Revert term/semester --- source/index.html.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/source/index.html.md b/source/index.html.md index ff5f312..d5f2287 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -170,18 +170,18 @@ curl --request GET \ "data": { "unarchived_courses": [ { - "term": "f19", + "semester": "f19", "title": "blank", "display_name": "", - "display_term": "Fall 2019" + "display_semester": "Fall 2019" } ], "archived_courses": [ { - "term": "f19", + "semester": "f19", "title": "sample", "display_name": "", - "display_term": "Fall 2019" + "display_semester": "Fall 2019" } ] } @@ -199,10 +199,10 @@ Get all the courses the user is taking or have taken. ```shell curl --request POST \ --url /api/courses \ - --form course_term=f19 \ + --form course_semester=f19 \ --form course_title=api \ --form head_instructor=instructor \ - --form base_course_term=f19 \ + --form base_course_semester=f19 \ --form base_course_title=sample \ --header 'Authorization: my_token' ``` @@ -219,10 +219,10 @@ Note that the endpoint builds a course based on a prior course offering (called Parameter | Description --------- | ----------- -course_term | term of the new course +course_semester | semester of the new course course_title | Title (or code) of the new course head_instructor | Head instructor of the new course -base_course_term | term of the base course +base_course_semester | semester of the base course base_course_title | Title (or code) of the base course # Courses.Users @@ -231,7 +231,7 @@ base_course_title | Title (or code) of the base course ```shell curl --request GET \ - --url /api///users \ + --url /api///users \ --header 'Authorization: my_token' ``` @@ -267,13 +267,13 @@ This end point gets all users in a course. ### HTTP Request -`GET /api///users` +`GET /api///users` ## Get Graders ```shell curl --request GET \ - --url /api///graders \ + --url /api///graders \ --header 'Authorization: my_token' ``` @@ -307,7 +307,7 @@ curl --request GET \ ### HTTP Request -`GET /api///graders` +`GET /api///graders` # Courses.Reports @@ -315,7 +315,7 @@ curl --request GET \ ```shell curl --request POST \ - --url /api///reports/summaries \ + --url /api///reports/summaries \ --header 'Authorization: my_token' ``` @@ -323,7 +323,7 @@ This endpoint helps system administrators set up cron jobs for automatic grade s ### HTTP Request -`POST /api///reports/summaries` +`POST /api///reports/summaries` # Gradeables @@ -331,7 +331,7 @@ This endpoint helps system administrators set up cron jobs for automatic grade s ```shell curl -X GET \ - /api///gradeable//values?user_id= + /api///gradeable//values?user_id= ``` > Possible response examples: @@ -359,11 +359,11 @@ curl -X GET \ } ``` -The endpoint returns values associated with an autograded gradeable with the given gradeable_id, which allows for determining a score on an assignment, if it has been graded, etc. +The endpoint returns values associated with an autograded gradeable with the given gradeable_id, which allows for desemesterining a score on an assignment, if it has been graded, etc. ### HTTP Request -`GET /api///gradeable//values?user_id=` +`GET /api///gradeable//values?user_id=` ### Parameters @@ -375,7 +375,7 @@ user_id | User's unique ID ```shell curl -X POST \ - /api///gradeable//upload\ + /api///gradeable//upload\ -F user_id=student \ -F vcs_checkout=true \ -F git_repo_id=true @@ -406,7 +406,7 @@ The endpoint requests for a VCS gradeable with the given gradeable_id to be subm ### HTTP Request -`POST /api///gradeable//upload` +`POST /api///gradeable//grade` ### Parameters From b0eb26a52b2d492fcb8628f4b772138cae1dbba7 Mon Sep 17 00:00:00 2001 From: IDzyre Date: Tue, 30 Apr 2024 09:52:42 -0700 Subject: [PATCH 4/4] remove comment changes --- source/index.html.md | 4 ++-- source/stylesheets/screen.css.scss | 14 +++++++++----- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/source/index.html.md b/source/index.html.md index d5f2287..928bd53 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -219,10 +219,10 @@ Note that the endpoint builds a course based on a prior course offering (called Parameter | Description --------- | ----------- -course_semester | semester of the new course +course_semester | Semester of the new course course_title | Title (or code) of the new course head_instructor | Head instructor of the new course -base_course_semester | semester of the base course +base_course_semester | Semester of the base course base_course_title | Title (or code) of the base course # Courses.Users diff --git a/source/stylesheets/screen.css.scss b/source/stylesheets/screen.css.scss index cd9b594..ed23b31 100644 --- a/source/stylesheets/screen.css.scss +++ b/source/stylesheets/screen.css.scss @@ -2,7 +2,7 @@ @import 'normalize'; @import 'variables'; @import 'icon-font'; -/*@import 'rtl'; // uncomment to switch to RTL format*/ +// @import 'rtl'; // uncomment to switch to RTL format /* Copyright 2008-2013 Concur Technologies, Inc. @@ -33,7 +33,7 @@ html, body { @extend %default-font; background-color: $main-bg; height: 100%; - -webkit-text-size-adjust: none; + -webkit-text-size-adjust: none; /* Never autoresize text */ } //////////////////////////////////////////////////////////////////////////////// @@ -62,6 +62,7 @@ html, body { font-size: 13px; font-weight: bold; + // language selector for mobile devices .lang-selector { display: none; a { @@ -70,6 +71,7 @@ html, body { } } + // This is the logo at the top of the ToC .logo { display: block; max-width: 100%; @@ -89,7 +91,7 @@ html, body { width: $nav-width - ($nav-padding*2); outline: none; color: $nav-text; - border-radius: 0; + border-radius: 0; /* ios has a default border radius */ } &:before { @@ -218,7 +220,7 @@ html, body { transform: rotate(-90deg) translate(-100%, 0); border-radius: 0 0 0 5px; } - padding: 0 1.5em 5em 0; + padding: 0 1.5em 5em 0; // increase touch size area display: none; position: fixed; top: 0; @@ -252,7 +254,7 @@ html, body { background-color: $main-bg; min-height: 100%; - padding-bottom: 1px; + padding-bottom: 1px; // prevent margin overflow // The dark box is what gives the code samples their dark background. // It sits essentially under the actual content block, which has a @@ -312,7 +314,9 @@ html, body { // This is all the stuff with the light background in the left half of the page .content { + // fixes webkit rendering bug for some: see #538 -webkit-transform: translateZ(0); + // to place content above the dark box position: relative; z-index: 30;