Add student API documentation

Author: IDzyre

source/index.html.md

@@ -16,6 +16,8 @@ search: true
 
 *Note: API is still a work in progress.*
 
+For the students, view <a href="/student_api">the student api</a>
+
 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).

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:
+  - <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a>
+
+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.*__
+
+<aside class="warning">
+The API is not formally versioned at this time, and its endpoints and their responses may change
+without warning. Use at your own risk!
+</aside>
+
+# 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`
+
+<aside class="notice">
+You must replace <code>my_token</code> with your personal API token.
+</aside>
+
+## Get Token
+
+```shell
+curl -X POST \
+  <base_url>/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 \
+  <base_url>/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 \
+  <base_url>/student_api/<term>/<course>/gradeable/<gradeable_id>/score?user_id=<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/<term>/<course>/gradeable/<gradeable_id>/score?user_id=<user_id>`
+
+### Parameters
+
+Parameter | Description
+--------- | -----------
+user_id | User's unique ID
+
+## Submit VCS Gradeable
+
+```shell
+curl -X POST \
+  <base_url>/student_api/<term>/<course>/gradeable/<gradeable_id>/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/<term>/<course>/gradeable/<gradeable_id>/upload`
+
+### Parameters
+
+Parameter | Description
+--------- | -----------
+user_id | User's unique ID
+

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;