API for staff

Scores

You should provide a list contains emails of your students, the target name and its deadline to get the scores.

POST

We should use GET with body to get the scores. It's wired to use GET with body, but the RFC 7230 on HTTP/1.1 says:

Request message framing is independent of method semantics, even if the method does not define any use for a message body.

But a lot existing http library don't provide GET with body, so we use POST.

The endpoint should be: https://test161.ops-class.org/api-v2/scores

Request Body

{
  "target": "asst1",
  "version": 1,
  "deadline": "2016-03-16T15:12:26.365Z",
  "users": [
    {
      "email": "email1@buffalo.edu",
      "group_size": 1,
      "deadline": "2016-03-29T15:12:26.365Z"
    },
    { "email": "email2@buffalo.edu" },
    { "email": "email3@buffalo.edu" }
  ]
}

Parameters

The target and users fields are required. target -> target name users -> users

The deadline, version are optional. deadline -> deadline for the target you queried, you can specific deadline for each user version -> target version, you may need this if you have multiple stage target

More details can found from this file.

Response

[
  {
    "email": "email1@buffalo.edu",
    "score": 50,
    "submission_time": "2016-03-15T05:19:36.365Z",
    "tests": [
      {
        "name": "build",
        "id": "build.t",
        "points_avail": 0,
        "points_earned": 0
      },
      {
        "name": "Test 1",
        "id": "tests/t1.t",
        "points_avail": 20,
        "points_earned": 20
      },
      {
        "name": "Test 2",
        "id": "tests/t2.t",
        "points_avail": 30,
        "points_earned": 30
      }
    ]
  },
  {
    "email": "email2@buffalo.edu",
    "score": 49,
    "submission_time": "2016-03-08T18:51:12.365Z",
    "tests": [
      {
        "name": "build",
        "id": "build.t",
        "points_avail": 0,
        "points_earned": 0
      },
      {
        "name": "Test 1",
        "id": "tests/t1.t",
        "points_avail": 20,
        "points_earned": 20
      },
      {
        "name": "Test 2",
        "id": "tests/t2.t",
        "points_avail": 30,
        "points_earned": 29
      }
    ]
  },
  {
    "email": "email3@buffalo.edu",
    "score": 47,
    "submission_time": "2016-03-10T19:05:51.365Z",
    "tests": [
      {
        "name": "build",
        "id": "build.t",
        "points_avail": 0,
        "points_earned": 0
      },
      {
        "name": "Test 1",
        "id": "tests/t1.t",
        "points_avail": 20,
        "points_earned": 19
      },
      {
        "name": "Test 2",
        "id": "tests/t2.t",
        "points_avail": 30,
        "points_earned": 29
      }
    ]
  }
]

Hide Students from leader boards

GET

Get all hidden users for a particular target.

Endpoint: https://test161.ops-class.org/api-v2/hiddens/{target_name}

Response:

[
  "email1@buffalo.edu",
  "email2@buffalo.edu",
  "email3@buffalo.edu"
]

POST

We should use POST to do change users hidden status:

Endpoint: https://test161.ops-class.org/api-v2/hiddens The hiddens is not good, we should use nouns in the url, maybe invisibles is better.

Body:

{
  "target": "asst1",
  "users": [
    {
      "email": "email1@buffalo.edu",
      "action": "hide"
    },
    {
      "email": "email2@buffalo.edu",
      "action": "show"
    },
    {
      "email": "email3@buffalo.edu",
      "action": "hide"
    }
  ]
}

or

{
  "target": "asst1",
  "action": "show",
  "users": [
    {
      "email": "email1@buffalo.edu"
    },
    {
      "email": "email2@buffalo.edu"
    },
    {
      "email": "email3@buffalo.edu"
    }
  ]
}

Response:

[
    {
      "email": "email1@buffalo.edu",
      "status": "hide"
    },
    {
      "email": "email2@buffalo.edu",
      "status": "show"
    },
    {
      "email": "email3@buffalo.edu",
      "status": "hide"
    }
]

Authentication

We can use the token of our test161 web app to authenticate two things:

1. It's a correct user.
2. It's a staff.

We may need to ask the staff its own email address to make sure the relationship of the staff and students.

Usage

The server will look forward the X-Auth-Token field in the request header. So please set the field with your token like:

"X-Auth-Token": "97f0ad9e24ca5e0408a269748d7fe0a0"