API Endpoints of pikne-zadania

Light
Dark

Discuss API v0.5 at #50.

Throwing errors

If there is an error (4xx or 5xx HTTP status code), the API will return either no content or the JSON object with an error message:

{
  "status": 500,
  "message": "<error message>"
}

The "status" property is a status code of the response.

The most common status codes

200 OK, when the request is succesful,
400 Bad Request, when the request is invalid,
401 Unauthorized, when the User must authenticate but the authentication failed or was not provided;
the unauthenticated will always get 401 Unauthorized instead of 403 Forbidden.
403 Forbidden, when the User is not authorized to make a request (see "It can be used by" section),
404 Not Found, when the requested resource does not exist,
500 Internal Server Error, when there is a problem on the server-side.

The request will have a 403 Forbidden status code instead of 404 Not Found one when a resource is unavailable for the User to list (or it would be if it existed).

Endpoints

Subject

GET /api/subject/list - list all available subjects

It can be used by

anyone.

Request

Response

{
  "subjects": ["fizyka", "_fizyka", "astronomia"]
}

Notes

There are only subjects available for the User.

POST /api/subject/create - create a new subject

It can be used by

all teachers.

Special status codes

409 Conflict - the name (the subject property) is already taken.

Request

{
  "subject": "fizyka",
  "assignees": [
    "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755"
  ]
}

Response

Notes

Subjects that begins with the _ character are private and not visible to unauthorized users.
Only the Admin will be managing the subject if the assignees property equals [].
subject is a name and an id simultaneously. It has to be unique.
If the assignees property equals null, all teachers will be able to manage the subject.

POST /api/subject/info - read assignees of a subject

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null.

Request

{
  "subject": "fizyka"
}

Response

{
  "assignees": [
    {
      "userId": "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755",
      "name": "Smith"
    }
  ]
}

Notes

If the assignees property equals null, all teachers can modify the subject.

POST /api/subject/permit - update assignees of a subject

It can be used by

all assignees of a subject.

Request

{
  "subject": "fizyka",
  "assignees": [
    "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755"
  ]
}

Response

Notes

If the assignees property equals null, all teachers will be able to manage the subject.

Problem managing

POST /api/subject/problem/render - render an exercise

It can be used by

anyone if a subject is public and an exercise is listed in a subject’s hierarchy,
all users if the exercise is added to their session,
all assignees of a subject.

Request

{
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa",
  "seed": 0
}

Response

{
  "type": "EqEx",
  "name": "Pociągi dwa 2",
  "done": 0.34,
  "problem": {
    "main": "Z miast \\(A\\) i \\(B\\) odległych o \\(d=300\\;\\mathrm{km}\\) wyruszają jednocześnie\ndwa pociągi z prędkościami \\(v_a= 50\\;\\mathrm{\\frac{km}{h}}\\) oraz \\(v_b=70\\;\\mathrm{\\frac{km}{h}}\\).\nW jakiej odległości \\(x\\) od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie \\(t\\) się to stanie?",
    "img": ["1.png", "2.png"],
    "unknown": [
      ["x", "\\mathrm{km}"],
      ["t", "\\mathrm{s}"]
    ]
  },
  "correctAnswer": {
    "answers": [2.5, 125]
  }
}

Notes

Only the Teacher and the Admin can use the seed property. Otherwise, the database provides it.
Only the Teacher and the Admin receive the correctAnswer property.
The done property can be null or a number from 0 up to and including 1, see #24.
The problem property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.
The problem property can contain links to static content. The User can access it via the GET /api/subject/static/:subject/:filename request.

POST /api/subject/problem/submit - submit an answer & store it

It can be used by

anyone if a subject is public and an exercise is listed in a subject’s hierarchy,
all users if the exercise is added to their session
all assignees of a subject.

Request

{
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa",
  "answer": {
    "answers": [15.000000000000004, 13]
  }
}

Response

{
  "info": [false, true]
}

Notes

The info property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.

Static files managing

POST /api/subject/static/list - list static files

It can be used by

all assignees of a subject.

Request

{
  "subject": "fizyka"
}

Response

{
  "filenames": ["rzeka.jpg"]
}

GET /api/subject/static/:subject/:filename - get a static file

It can be used by

anyone if a subject is public,
all users if the exercise mentioning the static file is added to their session,
all assignees of a subject.

Notes

There should be binary data with an appropriate Content-type in the response.

PUT /api/subject/static/:subject/:filename - upload a static file

It can be used by

all assignees of a subject.

Notes

The request data should follow the multipart/form-data Content-type.

Hierarchy modification

POST /api/subject/hierarchy/get - read an exercise hierarchy of a subject

It can be used by

anyone if a subject is public,
all assignees of a subject.

Request

{
  "subject": "fizyka",
  "raw": false
}

Response

[
  {
    "name": "",
    "children": [
      {
        "type": "EqEx",
        "name": "Kula 2",
        "children": "kula-2",
        "description": "TODO",
        "done": null
      }
    ]
  },
  {
    "name": "mechanika",
    "children": [
      {
        "name": "kinematyka",
        "children": [
          {
            "type": "EqEx",
            "name": "Pociągi dwa 2",
            "children": "pociagi-dwa",
            "description": "Z miast \\(A\\) i \\(B\\) odległych o \\(d= 300\\;\\mathrm{km}\\) wyruszają jednocześnie\ndwa pociągi z prędkościami \\(v_{a}= \\;\\mathrm{\\frac{km}{h}}\\) oraz \\(v_{b}= \\;\\mathrm{\\frac{km}{h}}\\).\nW jakiej odległości \\(x\\) od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie \\(t\\) się to stanie?\n",
            "done": 0.34
          }
        ]
      }
    ]
  }
]

Notes

If the raw property equals false, there is the description property and can be the optional done property if the User is authenticated.
If the raw property equals false and the User is authorized, there is a {"name": "", children: [...]} (sub-subject) object with all exercises not listed in the hierarchy.
The description property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.
The done property can be null or a number from 0 up to and including 1, see #24.

POST /api/subject/hierarchy/set - update an exercise hierarchy of a subject

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null.

Request

{
  "subject": "fizyka",
  "hierarchy": [
    {
      "name": "mechanika",
      "children": [
        {
          "name": "kinematyka",
          "children": [
            {
              "children": "pociagi-dwa"
            }
          ]
        }
      ]
    }
  ]
}

Response

Exercise modification

POST /api/subject/exercise/list - get all exercises from a subject

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null.

Request

{
  "subject": "_fizyka"
}

Response

{
  "exercises": [
    {
      "id": "kula-2",
      "type": "EqEx",
      "name": "Kula 2",
      "description": "TODO"
    },
    {
      "id": "pociagi-dwa",
      "type": "EqEx",
      "name": "Pociągi dwa 2",
      "description": "Z miast \\(A\\) i \\(B\\) odległych o \\(d= 300\\;\\mathrm{km}\\) wyruszają jednocześnie\ndwa pociągi z prędkościami \\(v_{a}= \\;\\mathrm{\\frac{km}{h}}\\) oraz \\(v_{b}= \\;\\mathrm{\\frac{km}{h}}\\).\nW jakiej odległości \\(x\\) od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie \\(t\\) się to stanie?\n"
    }
  ]
}

Notes

The description property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.

POST /api/subject/exercise/add - create an exercise

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null.

Special status codes

409 Conflict - the name (subject and exerciseId properties) is already taken.

Request

{
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa",
  "content": "---\ntype: EqEx\nname: Pociągi dwa 2\n---\nZ miast \\(A\\) i \\(B\\) odległych o d=300km wyruszają jednocześnie\ndwa pociągi z prędkościami v_a=[40;60]km/h oraz v_b=[60;80]km/h.\nW jakiej odległości x=?km od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie t=?h się to stanie?\n---\nt=d/(v_a+v_b)\nx=t*v_a\n"
}

Response

Notes

The content property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.
The content property can contain links to static content. The User can upload it via the PUT /api/subject/static/:subject/:filename request.

POST /api/subject/exercise/get - read a content of an exercise

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null,

Special status codes

200 OK, 403 Forbidden, 404 Not Found

Request

{
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa"
}

Response

{
  "content": "---\ntype: EqEx\nname: Pociągi dwa 2\n---\nZ miast \\(A\\) i \\(B\\) odległych o d=300km wyruszają jednocześnie\ndwa pociągi z prędkościami v_a=[40;60]km/h oraz v_b=[60;80]km/h.\nW jakiej odległości x=?km od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie t=?h się to stanie?\n---\nt=d/(v_a+v_b)\nx=t*v_a\n"
}

Notes

The content property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.

POST /api/subject/exercise/update - update a content of an exercise

It can be used by

all assignees of a subject,
or all teachers if a subject’s assignees equals null.

Request

{
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa",
  "content": "---\ntype: EqEx\nname: Pociągi dwa 2\n---\nZ miast \\(A\\) i \\(B\\) odległych o d=300km wyruszają jednocześnie\ndwa pociągi z prędkościami v_a=[40;60]km/h oraz v_b=[60;80]km/h.\nW jakiej odległości x=?km od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie t=?h się to stanie?\n---\nt=d/(v_a+v_b)\nx=t*v_a\n"
}

Response

Notes

Only the content property is changeable. Changing an exerciseId fails or overwrites an old exercise.
The content property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.

POST /api/subject/exercise/preview - render an exercise from a content

It can be used by

all authorized.

Request

{
  "content": "---\ntype: EqEx\nname: Pociągi dwa 2\n---\nZ miast \\(A\\) i \\(B\\) odległych o d=300km wyruszają jednocześnie\ndwa pociągi z prędkościami v_a=[40;60]km/h oraz v_b=[60;80]km/h.\nW jakiej odległości x=?km od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie t=?h się to stanie?\n---\nt=d/(v_a+v_b)\nx=t*v_a\n",
  "seed": 0
}

Response

{
  "type": "EqEx",
  "name": "Pociągi dwa 2",
  "problem": {
    "main": "Z miast \\(A\\) i \\(B\\) odległych o \\(d=300\\;\\mathrm{km}\\) wyruszają jednocześnie\ndwa pociągi z prędkościami \\(v_a= 50\\;\\mathrm{\\frac{km}{h}}\\) oraz \\(v_b=70\\;\\mathrm{\\frac{km}{h}}\\).\nW jakiej odległości \\(x\\) od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie \\(t\\) się to stanie?",
    "img": ["1.png", "2.png"],
    "unknown": [
      ["x", "\\mathrm{km}"],
      ["t", "\\mathrm{s}"]
    ]
  },
  "correctAnswer": {
    "answers": [2.5, 125]
  }
}

Notes

The seed property is optional.
The problem property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.
The problem property can contain links to static content. The User can access it via the GET /api/subject/static/:subject/:filename request.
The content property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.

Auth

POST /api/auth/register - create a new user

It can be used by

anyone who has a valid invitation.

Special status codes

409 Conflict - the login is already taken.

Request

{
  "login": "user@example.com",
  "name": "User",
  "hashedPassword": "r02H/fnQ3M3Xfjqsr3dg8mY78lBDXWoiR0O0JcXW8VM=",
  "number": 11,
  "invitation": "QwErTy58"
}

Response

Notes

This request doesn’t authenticate, unlike a POST /api/auth/login one.
The login property is an email address. With this request, it is not possible to register hard-coded users (like root).
The description of the hashedPassword property generation is here.
The number property is a number or null.

POST /api/auth/login - authenticate

It can be used by

anyone.

Request

{
  "login": "user@example.com",
  "hashedPassword": "r02H/fnQ3M3Xfjqsr3dg8mY78lBDXWoiR0O0JcXW8VM="
}

Response

Notes

The description of the hashedPassword property generation is here.

POST /api/auth/logout - unauthenticate

It can be used by

all authorized.

Request

Response

User

POST /api/user/info - read user’s info

It can be used by

all authorized if a request is referring to the User,
the assignee of the team of the requested user.

Request

{
  "userId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Response

{
  "name": "User",
  "teamId": 2,
  "number": 11
}

Notes

Omitting the userId property causes using the User’s one.
The number property is a number or null.

POST /api/user/update - update user’s info

It can be used by

the assignee of the team of the requested user.

Request

{
  "userId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "number": 33
}

Response

Notes

Only number and name properties are changeable.
The number property is a number or null.

POST /api/user/delete - delete a user

It can be used by

the assignee of the team of the requested user.

Request

{
  "userId": "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755"
}

Response

Team

GET /api/team/list - list all teams

It can be used by

all teachers.

Request

Response

[
  {
    "teamId": 1,
    "name": "Teachers",
    "assignee": {
      "userId": "4813494d137e1631bba301d5acab6e7bb7aa74ce1185d456565ef51d737677b2",
      "name": "root"
    },
    "invitation": "QwErTy58"
  },
  {
    "teamId": 2,
    "name": "2d",
    "assignee": {
      "userId": "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755",
      "name": "Smith"
    },
    "invitation": null
  },
  {
    "teamId": 3,
    "name": "3d",
    "assignee": {
      "userId": "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755",
      "name": "Smith"
    },
    "invitation": null
  }
]

Notes

There is always a hard-coded admin team with id 0.
If the User can manage a team, there is the invitation property there.
When a team has closed registration, the invitation property is null.

POST /api/team/create - create a team

It can be used by

all teachers.

Request

{
  "name": "2d"
}

Response

{
  "teamId": 2
}

POST /api/team/info - read team’s info

It can be used by

all authorized if a request is referring to the User’s team,
all teachers.

Request

{
  "teamId": 2
}

Response

{
  "name": "2d",
  "assignee": {
    "userId": "1057a9604e04b274da5a4de0c8f4b4868d9b230989f8c8c6a28221143cc5a755",
    "name": "Smith"
  },
  "invitation": "QwErTy58",
  "members": [
    {
      "userId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "name": "User",
      "number": 11
    }
  ]
}

Notes

The Student will not receive the invitation property and any of userId properties.
When a team has closed registration, the invitation property is null.

POST /api/team/update - update team’s info

It can be used by

the assignee of the requested team,

Special status codes

409 Conflict - the invitation is already taken.

Request

{
  "teamId": 2,
  "invitation": "QwErTy58"
}

Response

Notes

Only a teacher can be an assignee of a team.
Only invitation, assignee and name properties are changeable.
The invitation property can also be an empty string "" (in that case, it will be random) or null (in that case, registration will be closed).

POST /api/team/delete - delete a team

It can be used by

the assignee of the requested team.

Request

{
  "teamId": 2
}

Response

Session

POST /api/session/reset - drop and create a session

Remember to save a report via the POST /api/session/report/save request.

It can be used by

all assignees.

Request

{
  "teamId": 2
}

Response

Notes

It is irreversible.

POST /api/session/add - add an exercise to the session

It can be used by

all teachers if a subject is public and an exercise is listed in a subject’s hierarchy,
all assignees of a subject.

Special status codes

409 Conflict - if the session is already finished.

Request

{
  "teamId": 2,
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa-2"
}

Response

POST /api/session/delete - remove the exercise from the session

It can be used by

all teachers.

Request

{
  "teamId": 2,
  "subject": "fizyka",
  "exerciseId": "pociagi-dwa-2"
}

Response

POST /api/session/list - generate a list of exercises in the current session for the users

It can be used by

all authorized excluding teachers.

Request

Response

[
  {
    "type": "EqEx",
    "name": "Kula 2",
    "subject": "_fizyka",
    "exerciseId": "kula-2",
    "description": "TODO",
    "done": null
  },
  {
    "type": "EqEx",
    "name": "Pociągi dwa 2",
    "subject": "fizyka",
    "exerciseId": "pociagi-dwa",
    "description": "Z miast \\(A\\) i \\(B\\) odległych o \\(d= 300\\;\\mathrm{km}\\) wyruszają jednocześnie\ndwa pociągi z prędkościami \\(v_{a}= \\;\\mathrm{\\frac{km}{h}}\\) oraz \\(v_{b}= \\;\\mathrm{\\frac{km}{h}}\\).\nW jakiej odległości \\(x\\) od miasta \\(A\\) spotkają się te pociągi?\nPo jakim czasie \\(t\\) się to stanie?\n",
    "done": 0.34
  }
]

Notes

The description property is dependent on exercise type (ExT). The one shown above is the EquationExercise (EqEx) one.
The done property can be null or a number from 0 up to and including 1, see #24.
The subject and the exerciseId properties mention exercises added to the session. The User can access it via the POST /api/subject/problem/render request.

POST /api/session/status - generate a current report without saving it

It can be used by

all assignees.

Request

{
  "teamId": 2
}

Response

{
  "finished": true,
  "exercises": [
    {"subject": "fizyka", "exerciseId": "pociagi-dwa-1"},
    {"subject": "fizyka", "exerciseId": "pociagi-dwa-2"},
    {"subject": "fizyka", "exerciseId": "pociagi-dwa-3"},
    {"subject": "fizyka", "exerciseId": "pociagi-dwa-4"}
  ],
  "report": [
    {
      "userId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "exercises": ["☐", "☒", "⚀", "☑"]
    }
  ]
}

Notes

The exercises properties nested in report are tuples with the same length as the exercises property.
The exercises properties nested in report have elements with four possible values, i.e.
- ☐ (U+2610) - unattempted
- ☒ (U+2612) - incorrect answer
- ⚀ (U+2680) - partial answer
- ☑ (U+2611) - correct answer

POST /api/session/end - end a session / block adding new submits

It can be used by

all assignees.

Request

{
  "teamId": 2
}

Response

Reports

POST /api/session/report/list - list reports

It can be used by

all teachers.

Request

{
  "teamId": 3
}

Response

{
  "filenames": [
    "report_3_2022-05-26T23:33:36+02:00.txt",
    "report_π_2022-05-27T01:33:66+02:00.txt"
  ]
}

Notes

Generated reports can be downloaded via the GET /api/session/static/:filename request.

POST /api/session/report/save - save a report to disk

It can be used by

all teachers.

Request

{
  "teamId": 2
}

Response

{
  "filename": "report_2_2022-05-26T23:33:36+02:00.txt"
}

Notes

Generated reports can be downloaded via the GET /api/session/static/:filename request.

GET /api/session/static/:filename - get a static file

It can be used by

all teachers.

Notes

There should be binary data with an appropriate Content-type in the response.

POST /api/session/report/delete - delete a report

It can be used by

all teachers.

Request

{
  "filename": "report_π_2022-05-27T01:33:66+02:00.txt"
}

Response

The project has been made by students of 8th High School of Maria Skłodowska-Curie in Katowice (class 2d in 2020/2021).
© 2021 Nircek (Marcin Zepp), Marwyk2003 (Marcin Wykpis), miloszwasacz (Miłosz Wąsacz), MichalTheProgrammer (Michał Szymocha)
This project is licensed under the terms of the GNU AGPL v3 or later.