-
-
Save jy95/d7b53648eb756547eb67fd0db962f68d to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.0 | |
info: | |
description: API for Source Code | |
version: 1.0.0 | |
title: Source Code API | |
license: | |
name: GPL-3.0-or-later | |
url: https://choosealicense.com/licenses/gpl-3.0/ | |
servers: | |
- url: http://localhost:3000 | |
description: Internal staging server for testing | |
- url: http://api.example.com/v1 | |
description: Optional server description, e.g. Main (production) server | |
tags: | |
- name: guest | |
description: Everything a(n) visitor / not authentified user could do | |
- name: user | |
description: Everything an authentified user could do (more than a guest) | |
- name: admin | |
description: Everything an administrator could do (more than an user) | |
paths: | |
/auth/login: | |
post: | |
summary: Logs user into the system | |
operationId: signIn | |
x-controller: auth | |
x-operation: signIn | |
tags: | |
- guest | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
password: | |
type: string | |
format: password | |
example: "42" | |
required: | |
- password | |
responses: | |
"200": | |
description: A JSON containing the JWT Token and some information about the user | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
token: | |
type: string | |
description: The JWT Token | |
required: | |
- token | |
- type: object | |
description: Some basic information on this user | |
properties: | |
user: | |
type: object | |
properties: | |
fullName: | |
type: string | |
description: The full name of this user | |
example: Alexandre Dewit | |
minLength: 1 | |
maxLength: 50 | |
role: | |
type: string | |
enum: | |
- admin | |
- user | |
description: What kind of user are we ? | |
required: | |
- fullName | |
- role | |
required: | |
- user | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
message: | |
type: string | |
description: The main error message ( for example "Bad Request", | |
"Unauthorized", etc. ) | |
errors: | |
type: array | |
items: | |
type: object | |
description: Explanation about an error | |
required: | |
- message | |
- errors | |
/auth/register: | |
post: | |
summary: Creates a new user into the system | |
operationId: register | |
x-controller: auth | |
x-operation: register | |
tags: | |
- guest | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
password: | |
type: string | |
format: password | |
example: "42" | |
required: | |
- password | |
- type: object | |
properties: | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of this new user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/auth/me: | |
get: | |
summary: Fetch information about the current logged user | |
operationId: me | |
x-controller: users | |
x-operation: me | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
responses: | |
"200": | |
description: User data | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
- type: object | |
properties: | |
role: | |
type: string | |
enum: | |
- admin | |
- user | |
default: user | |
description: | | |
The type of user. Currently, 2 types are possibles : | |
1. user : The defaut ( an simple registered user ) | |
2. admin : User with additional credentials | |
id: | |
type: integer | |
description: The UUID of this user | |
example: 42 | |
required: | |
- role | |
- id | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/auth/update: | |
put: | |
summary: Update information about an user | |
description: > | |
Any user can freely any information about (him/her)self (except the | |
optional "id" / "role" fields ). | |
An admin can freely update any user and it is the only one that can use the "id" / "role" fields. | |
operationId: updateUser | |
x-controller: users | |
x-operation: updateUser | |
tags: | |
- user | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1auth~1me/get/responses/200/content/application~1\ | |
json/schema/allOf/0" | |
- type: object | |
properties: | |
password: | |
type: string | |
format: password | |
example: "42" | |
role: | |
$ref: "#/paths/~1auth~1me/get/responses/200/content/applicati\ | |
on~1json/schema/allOf/1/properties/role" | |
id: | |
type: integer | |
description: The UUID of this user. By default, it will take the one | |
of logged user | |
example: 42 | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/create_exercise: | |
post: | |
summary: Creates a new exercise into the system | |
description: > | |
Creates a new exercise into the system. | |
By default (if nothing specified), the exercise will be in state "DRAFT". | |
You are free to add new tags / keywords but you must add at least 3 validated tags. | |
The following restrictions are applied on simple user(s) (no restriction for admin): | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed for the field "state" : | |
- DRAFT | |
- PENDING | |
operationId: createSingleExercise | |
x-controller: exercises | |
x-operation: createSingleExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
multipart/form-data: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1api~1create_exercise/post/requestBody/content/ap\ | |
plication~1json/schema" | |
- type: object | |
properties: | |
exerciseFile: | |
type: string | |
format: binary | |
description: The sources of this exercise, in zip format | |
required: | |
- exerciseFile | |
encoding: | |
exerciseFile: | |
contentType: application/zip, application/x-zip-compressed, multipart/x-zip | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
"/api/exercises/{id}": | |
parameters: | |
- name: id | |
in: path | |
description: The exercise ID | |
required: true | |
schema: | |
type: integer | |
- name: includeOptions | |
in: query | |
description: To include additional properties when fetching exercise | |
style: deepObject | |
schema: | |
type: object | |
description: To include additional properties when fetching exercise(s) | |
properties: | |
includeCreator: | |
type: boolean | |
default: false | |
description: Must we include the creator of exercise(s) ? | |
includeMetrics: | |
type: boolean | |
default: true | |
description: Must we include the metrics of exercise(s) ? | |
includeDescription: | |
type: boolean | |
default: true | |
description: Must we include the description of exercise(s) ? | |
includeTags: | |
type: boolean | |
default: true | |
description: Must we include the tags of exercise(s) ? | |
get: | |
summary: Retrieve this specific exercise data | |
operationId: getExerciseByID | |
x-controller: exercises | |
x-operation: getExerciseByID | |
security: | |
- {} | |
- bearerAuth: [] | |
tags: | |
- guest | |
- user | |
responses: | |
"200": | |
description: Exercise data inside a JSON | |
content: | |
application/json: | |
schema: | |
allOf: | |
- allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
metrics: | |
type: object | |
description: The metrics of the exercise (present only if | |
includeMetrics is true) | |
properties: | |
votes: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: Number of votes for this exercise | |
avg_score: | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
description: The average score of this exercise | |
required: | |
- votes | |
- avg_score | |
tags: | |
type: array | |
description: The tags of the exercise (present only if | |
includeTags is true) | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category: | |
type: object | |
properties: | |
category_text: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of the Tag Category linked | |
with this tag | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category ID linked with this tag | |
required: | |
- category_text | |
- category_id | |
isValidated: | |
type: boolean | |
default: false | |
example: false | |
description: Is this tag validated or not ? | |
required: | |
- category | |
- isValidated | |
uniqueItems: true | |
creator: | |
allOf: | |
- type: object | |
description: The creator of the exercise (present only if | |
includeMetrics is true) | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
- type: object | |
properties: | |
vote: | |
type: number | |
minimum: 0 | |
example: 5 | |
description: If this endpoint was used by an authentified user, it | |
will fetch his/her vote if it exists | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Update this specific exercise data | |
description: > | |
Update this specific exercise data | |
You are free to add new tags / keywords but you **must** add at least 3 validated tags. | |
The following restrictions are applied on simple user(s) (no restriction for admin) : | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed for the field "state" : | |
- DRAFT | |
- PENDING | |
operationId: UpdateExercise | |
x-controller: exercises | |
x-operation: UpdateExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is | |
related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
- type: object | |
properties: | |
version: | |
type: integer | |
description: The version of this exercise (optimistic lock) | |
minimum: 0 | |
example: 42 | |
required: | |
- version | |
- type: object | |
properties: | |
removePreviousFile: | |
type: boolean | |
default: false | |
example: true | |
description: If set to true, the API will delete the previous file | |
when updating the exercise | |
multipart/form-data: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1api~1exercises~1%7Bid%7D/put/requestBody/content\ | |
/application~1json/schema/allOf/0" | |
- type: object | |
description: If we want to also to change the sources zip file of this | |
exercise | |
properties: | |
exerciseFile: | |
type: string | |
format: binary | |
description: The sources of this exercise, in zip format | |
required: | |
- exerciseFile | |
encoding: | |
exerciseFile: | |
contentType: application/zip, application/x-zip-compressed, multipart/x-zip | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/export: | |
post: | |
operationId: ExportExercises | |
x-controller: exercises | |
x-operation: ExportExercises | |
description: > | |
To export exercises that match optional criteria. | |
The JSON result is compliant with the [format](https://github.com/SourceCodeOER/cli#what-is-the-format-of-the-json-object-) | |
of our [cli](https://github.com/SourceCodeOER/cli) which means that if you wish to reupload the exercises in the future, | |
it's simple as you just have to rely on the [cli](https://github.com/SourceCodeOER/cli) command "uploader". | |
Please consider the following facts before using it : | |
1. Don't forget to rename the key "categories" to "own_categories" | |
2. If you wish to upload them without their files, remove the property "file" in each exercise : | |
```js | |
let json_result = { /* ... */ }; | |
const exercisesWithoutFile = json_result["exercises"].map(exercise => { | |
delete exercise["file"] | |
return exercise; | |
}); | |
Object.assign(json_result, { "exercises": exercisesWithoutFile }); | |
``` | |
3. If you wish to upload them with their files, download their files and modify each property "file" according our [format](https://github.com/SourceCodeOER/cli#what-is-the-format-of-the-json-object-) | |
of our [cli](https://github.com/SourceCodeOER/cli). | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: false | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
orderBy: | |
description: > | |
If you wish to order the provided result, use this | |
parameter. | |
For example, if you wish to first sort by date descending then by title ascending, you could achieve that with : | |
``` | |
[ | |
{"field": "date", "value": "DESC"}, | |
{"field": "title", "value": "ASC"} | |
] | |
``` | |
type: array | |
maxItems: 6 | |
items: | |
type: object | |
properties: | |
field: | |
type: string | |
description: > | |
The field we want to use for sorting. Currently, you | |
have the following possibilities : | |
1. state : the state of the exercise | |
2. id : the id of the exercise | |
3. title : the title of the exercise | |
4. date : the date of the last modification of the exercise | |
5. avg_score : the average score of the exercise | |
6. vote_count : the number of voters for this exercise | |
enum: | |
- state | |
- id | |
- title | |
- date | |
- avg_score | |
- vote_count | |
value: | |
type: string | |
enum: | |
- ASC | |
- DESC | |
description: | | |
The order we want to sort the related field : | |
- ASC : ASCENDING sorting | |
- DESC : DESCENDING sorting | |
data: | |
type: object | |
description: Search criterias | |
properties: | |
title: | |
type: string | |
description: Something we want to find inside the title of exercises | |
maxLength: 100 | |
example: SINF2MS | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
format: int32 | |
example: 1 | |
- type: array | |
items: | |
type: integer | |
format: int32 | |
minItems: 1 | |
description: Tags search encoded in Conjunctive Normal Form. (for NOT | |
predicat, use a negative integer) | |
example: | |
- -1 | |
- - 2 | |
- 3 | |
user_ids: | |
type: array | |
description: Filter the exercises by their creators. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An user ID | |
uniqueItems: true | |
exercise_ids: | |
type: array | |
description: Filter the exercises by their ids. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An exercise ID | |
uniqueItems: true | |
vote: | |
description: Only take exercises that meet a given threshold | |
type: object | |
properties: | |
operator: | |
description: The operation we want to apply | |
type: string | |
enum: | |
- <= | |
- < | |
- ">=" | |
- ">" | |
value: | |
description: The threshold value | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
required: | |
- operator | |
- value | |
filterOptions: | |
type: object | |
description: | | |
To filter some properties when fetching exercise(s) | |
properties: | |
state: | |
type: array | |
description: Filter the exercises by their state. By default, no | |
filtering is done. | |
items: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
maxItems: 5 | |
tags: | |
type: string | |
description: > | |
Filter the tags linked to exercise by their validity. | |
The default value ('default') stands for no filtering. | |
enum: | |
- default | |
- validated | |
- pending | |
default: default | |
responses: | |
"200": | |
description: Exercises data inside a JSON | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercises: | |
description: The fetched exercises (with their tags) | |
type: array | |
items: | |
allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
tags: | |
type: array | |
description: The tags linked to this exercise | |
items: | |
type: object | |
properties: | |
text: | |
type: string | |
description: The text of this Tag | |
example: INGINIOUS | |
minLength: 1 | |
maxLength: 100 | |
category: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category of this tag | |
isValidated: | |
type: boolean | |
default: false | |
example: false | |
description: Is this tag validated or not ? | |
required: | |
- isValidated | |
- category | |
- text | |
required: | |
- tags | |
categories: | |
description: Map whose keys are the IDS of the categories and value | |
their text | |
type: object | |
example: | |
"1": source | |
"2": institution | |
"3": auteur | |
required: | |
- exercises | |
- categories | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/search: | |
post: | |
summary: Search exercises that matches criteria | |
tags: | |
- guest | |
operationId: searchExercises | |
x-controller: exercises | |
x-operation: searchExercises | |
requestBody: | |
required: false | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
orderBy: | |
description: > | |
If you wish to order the provided result, use this | |
parameter. | |
For example, if you wish to first sort by date descending then by title ascending, you could achieve that with : | |
``` | |
[ | |
{"field": "date", "value": "DESC"}, | |
{"field": "title", "value": "ASC"} | |
] | |
``` | |
type: array | |
maxItems: 6 | |
items: | |
type: object | |
properties: | |
field: | |
type: string | |
description: > | |
The field we want to use for sorting. Currently, | |
you have the following possibilities : | |
1. state : the state of the exercise | |
2. id : the id of the exercise | |
3. title : the title of the exercise | |
4. date : the date of the last modification of the exercise | |
5. avg_score : the average score of the exercise | |
6. vote_count : the number of voters for this exercise | |
enum: | |
- state | |
- id | |
- title | |
- date | |
- avg_score | |
- vote_count | |
value: | |
type: string | |
enum: | |
- ASC | |
- DESC | |
description: | | |
The order we want to sort the related field : | |
- ASC : ASCENDING sorting | |
- DESC : DESCENDING sorting | |
data: | |
type: object | |
description: Search criterias | |
properties: | |
title: | |
type: string | |
description: Something we want to find inside the title of | |
exercises | |
maxLength: 100 | |
example: SINF2MS | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
format: int32 | |
example: 1 | |
- type: array | |
items: | |
type: integer | |
format: int32 | |
minItems: 1 | |
description: Tags search encoded in Conjunctive Normal Form. (for | |
NOT predicat, use a negative integer) | |
example: | |
- -1 | |
- - 2 | |
- 3 | |
user_ids: | |
type: array | |
description: Filter the exercises by their creators. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An user ID | |
uniqueItems: true | |
exercise_ids: | |
type: array | |
description: Filter the exercises by their ids. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An exercise ID | |
uniqueItems: true | |
vote: | |
description: Only take exercises that meet a given threshold | |
type: object | |
properties: | |
operator: | |
description: The operation we want to apply | |
type: string | |
enum: | |
- <= | |
- < | |
- ">=" | |
- ">" | |
value: | |
description: The threshold value | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
required: | |
- operator | |
- value | |
filterOptions: | |
type: object | |
description: | | |
To filter some properties when fetching exercise(s) | |
properties: | |
state: | |
type: array | |
description: Filter the exercises by their state. By default, no | |
filtering is done. | |
items: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, | |
5 states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
maxItems: 5 | |
tags: | |
type: string | |
description: > | |
Filter the tags linked to exercise by their | |
validity. The default value ('default') stands for | |
no filtering. | |
enum: | |
- default | |
- validated | |
- pending | |
default: default | |
- type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
page: | |
type: integer | |
description: Page number (start at 1) | |
minimum: 1 | |
default: 1 | |
example: 1 | |
size: | |
type: integer | |
minimum: 0 | |
description: Number of items by page | |
default: 10 | |
example: 10 | |
maximum: 50 | |
includeOptions: | |
type: object | |
description: To include additional properties when fetching | |
exercise(s) | |
properties: | |
includeCreator: | |
type: boolean | |
default: false | |
description: Must we include the creator of exercise(s) ? | |
includeMetrics: | |
type: boolean | |
default: true | |
description: Must we include the metrics of exercise(s) ? | |
includeDescription: | |
type: boolean | |
default: true | |
description: Must we include the description of exercise(s) ? | |
includeTags: | |
type: boolean | |
default: true | |
description: Must we include the tags of exercise(s) ? | |
examples: | |
searchExample1: | |
description: Search the first 10 exercises that have 'Java' in their title | |
and have some specific tags ( 1 AND (2 OR 3 OR 4) ) | |
value: | |
data: | |
title: Java | |
tags: | |
- 1 | |
- - 2 | |
- 3 | |
- 4 | |
searchExample2: | |
description: Search the exercises on page 2 that have 'Java' in their title | |
but with specific tags ( (NOT 1) AND (2 OR 3) ) | |
value: | |
metadata: | |
page: 2 | |
size: 10 | |
data: | |
title: Java | |
tags: | |
- -1 | |
- - 2 | |
- 3 | |
responses: | |
"200": | |
description: An object that contains the results and additionnal information | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
currentPage: | |
type: integer | |
example: 1 | |
minimum: 1 | |
description: Current number of page | |
default: 1 | |
totalItems: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: How much items match the given criterias | |
totalPages: | |
type: integer | |
minimum: 0 | |
example: 5 | |
description: How much pages match the given criterias | |
pageSize: | |
type: integer | |
minimum: 0 | |
example: 10 | |
default: 10 | |
description: How many entries on each page | |
required: | |
- currentPage | |
- totalItems | |
- totalPages | |
- pageSize | |
data: | |
type: array | |
items: | |
allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
metrics: | |
type: object | |
description: The metrics of the exercise (present only if | |
includeMetrics is true) | |
properties: | |
votes: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: Number of votes for this exercise | |
avg_score: | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
description: The average score of this exercise | |
required: | |
- votes | |
- avg_score | |
tags: | |
type: array | |
description: The tags of the exercise (present only if | |
includeTags is true) | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category: | |
type: object | |
properties: | |
category_text: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of the Tag Category | |
linked with this tag | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category ID linked with this | |
tag | |
required: | |
- category_text | |
- category_id | |
isValidated: | |
type: boolean | |
default: false | |
example: false | |
description: Is this tag validated or not ? | |
required: | |
- category | |
- isValidated | |
uniqueItems: true | |
creator: | |
allOf: | |
- type: object | |
description: The creator of the exercise (present only if | |
includeMetrics is true) | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
required: | |
- metadata | |
- data | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags: | |
post: | |
summary: Submit a tag proposal | |
tags: | |
- user | |
operationId: submitTagProposal | |
x-controller: tags | |
x-operation: submitTagProposal | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Validate or modify a Tag | |
tags: | |
- admin | |
operationId: updateTag | |
x-controller: tags | |
x-operation: updateTag | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
isValidated: | |
type: boolean | |
example: false | |
description: Is this tag validated or not | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
example: 42 | |
required: | |
- category_id | |
- isValidated | |
- version | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
get: | |
summary: Retrieve all tags | |
tags: | |
- guest | |
operationId: getTags | |
x-controller: tags | |
x-operation: getTags | |
parameters: | |
- in: query | |
name: tags_ids | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
description: Only consider the given tag ID(S) | |
- in: query | |
name: categories_ids | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
description: Only consider the given tag categories ID(S) | |
- in: query | |
name: state | |
schema: | |
type: string | |
enum: | |
- default | |
- validated | |
- pending | |
default: default | |
description: Filter the tags by their validity. The default value ('default') | |
stands for no filtering. | |
- in: query | |
name: title | |
schema: | |
type: string | |
description: Filter the tags by their text (case-insensitive comparison) | |
maxLength: 100 | |
responses: | |
"200": | |
description: An array of tag | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: "#/paths/~1api~1tags/put/requestBody/content/application~1j\ | |
son/schema" | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags_categories: | |
get: | |
summary: Retrieve only Tag categories | |
operationId: getTagCategories | |
x-controller: tags_categories | |
x-operation: getTagCategories | |
tags: | |
- guest | |
parameters: | |
- in: query | |
name: fetchStats | |
schema: | |
type: integer | |
enum: | |
- 0 | |
- 1 | |
description: If set to 1, it means that you enabled. Otherwise (0 or not | |
defined), you disabled it | |
description: If enabled, you can retrieve extra properties with the tag category | |
responses: | |
"200": | |
description: An array of tag categories | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
allOf: | |
- type: object | |
properties: | |
id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: The Id of this Tag_Category | |
category: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of this Tag_Category | |
required: | |
- id | |
- category | |
- type: object | |
description: "If queryParameter 'fetchStats' is set to 1, you can | |
retrieve the following count properties :" | |
properties: | |
total: | |
type: integer | |
description: The total number of tags under this tag category | |
minimum: 0 | |
total_validated: | |
type: integer | |
description: The total number of vamodated tags under this tag | |
category | |
minimum: 0 | |
total_unvalidated: | |
type: integer | |
description: The total number of vamodated tags under this tag | |
category | |
minimum: 0 | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Update a Tag category | |
operationId: updateTagCategory | |
x-controller: tags_categories | |
x-operation: updateTagCategory | |
security: | |
- bearerAuth: [] | |
tags: | |
- admin | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1api~1tags_categories/get/responses/200/content/appli\ | |
cation~1json/schema/items/allOf/0" | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags_by_categories: | |
get: | |
summary: Retrieve Tag categories with their related tags | |
tags: | |
- guest | |
operationId: getTagCategoriesWithTags | |
x-controller: tags_categories | |
x-operation: getTagCategoriesWithTags | |
parameters: | |
- in: query | |
name: state | |
schema: | |
type: string | |
enum: | |
- default | |
- validated | |
- pending | |
default: default | |
description: Filter the tags by their validity. The default value ('default') | |
stands for no filtering. | |
- in: query | |
name: onlySelected | |
schema: | |
type: array | |
description: If not empty, only consider the given tag categories ID(S). If | |
empty, no tag category is ignored | |
default: [] | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A Tag Category ID | |
responses: | |
"200": | |
description: An array of Tag category with their related tags | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
allOf: | |
- type: object | |
properties: | |
id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: The Id of this Tag_Category | |
category: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of this Tag_Category | |
required: | |
- id | |
- category | |
- type: object | |
properties: | |
tags: | |
type: array | |
description: An array of related tags to this Tag Category | |
minItems: 1 | |
uniqueItems: true | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
isValidated: | |
type: boolean | |
example: false | |
description: Is this tag validated or not | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
example: 42 | |
required: | |
- category_id | |
- isValidated | |
- version | |
required: | |
- tags | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_exercises: | |
post: | |
summary: Creates multiple exercises into the system | |
description: > | |
Creates multiple exercises into the system | |
By default (if nothing specified), an exercise will be in state "DRAFT". | |
tags: | |
- admin | |
operationId: createMultipleExercises | |
x-controller: bulk | |
x-operation: createMultipleExercises | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
multipart/form-data: | |
schema: | |
type: object | |
properties: | |
exercisesData: | |
$ref: "#/paths/~1api~1bulk~1create_exercises/post/requestBody/con\ | |
tent/application~1json/schema" | |
files: | |
type: array | |
description: The sources of the exercises, each in zip format | |
minItems: 1 | |
items: | |
type: string | |
format: binary | |
description: The source of an exercise, in zip format | |
filesMapping: | |
type: array | |
description: Mapping between the given file (to find out which data | |
belong to exercise) | |
minItems: 1 | |
items: | |
type: object | |
properties: | |
filename: | |
type: string | |
description: The name of the given source file | |
example: file1.zip | |
exercise: | |
type: integer | |
description: The location of the related exercise in the | |
exercisesData array | |
required: | |
- filename | |
- exercise | |
required: | |
- exercisesData | |
- files | |
- filesMapping | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_or_find_tag_categories: | |
post: | |
summary: Creates or Find tag categories | |
x-controller: bulk | |
x-operation: createOrFindTagCategories | |
tags: | |
- admin | |
operationId: createOrFindTagCategories | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
oneOf: | |
- type: string | |
description: The name of the Tag Category | |
example: author | |
- type: object | |
description: Category to add, under one that already exists | |
properties: | |
text: | |
type: string | |
description: The name of the Tag Category | |
example: author | |
minLength: 3 | |
maxLength: 100 | |
category: | |
type: integer | |
format: int32 | |
minimum: 0 | |
description: The ID of the Tag Category parent | |
required: | |
- text | |
- category | |
responses: | |
"200": | |
description: An array of tag categories | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: "#/paths/~1api~1tags_categories/get/responses/200/content/a\ | |
pplication~1json/schema/items/allOf/0" | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/modify_exercises_status: | |
put: | |
summary: Change the status of given exercises | |
description: > | |
Change the status of given exercises. | |
The following restrictions are applied on simple user(s) (no restriction for admin): | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed : | |
- DRAFT | |
- PENDING | |
- ARCHIVED | |
operationId: ChangeExercisesStatus | |
x-controller: bulk | |
x-operation: ChangeExercisesStatus | |
tags: | |
- admin | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercises: | |
type: array | |
description: An array of exercises IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: An exercise ID | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 states | |
are possibles : | |
1. DRAFT : The default state (for example when a exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- exercises | |
- state | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_exercises: | |
delete: | |
summary: Delete given exercises | |
description: > | |
Permanently remove from system the given exercises. (No way to retrieve | |
them after this) | |
Otherwise, if you simply want to soft delete/hide these exercises, use [this endpoint](#operation/ChangeExercisesStatus) to change their status to ARCHIVED. | |
operationId: DeleteExercises | |
x-controller: bulk | |
x-operation: DeleteExercises | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of exercises IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: An exercise ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_tags: | |
delete: | |
summary: Delete given tags | |
description: Delete given tags. | |
operationId: DeleteTags | |
x-controller: bulk | |
x-operation: DeleteTags | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of tags IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A tag ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_tags_categories: | |
delete: | |
summary: Delete given tags categories | |
description: Delete given tags categories. | |
operationId: DeleteTagCategories | |
x-controller: bulk | |
x-operation: DeleteTagCategories | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of tag category IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A tag category ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_tags: | |
post: | |
summary: Creates multiple tags into the system | |
tags: | |
- user | |
operationId: createMultipleTags | |
x-controller: bulk | |
x-operation: createMultipleTags | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
allOf: | |
- $ref: "#/paths/~1api~1tags/post/requestBody/content/application\ | |
~1json/schema" | |
- type: object | |
properties: | |
isValidated: | |
type: boolean | |
example: false | |
default: false | |
description: Should this tag validated or not ? By default, this | |
tag is not validated | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/vote_for_exercise: | |
post: | |
summary: Vote (or update the vote) of the current logged user for given exercise | |
operationId: voteForExercise | |
x-controller: exercises | |
x-operation: voteForExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercise_id: | |
type: integer | |
minimum: 0 | |
description: The ID of the exercise we want to vote / modify a vote | |
example: 42 | |
score: | |
type: number | |
format: double | |
minimum: 0 | |
example: 5 | |
description: The score we want to give to this exercise | |
required: | |
- score | |
- exercise_id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/configurations: | |
get: | |
description: Get all configurations of the current logged user | |
operationId: FetchOwnConfigurations | |
x-controller: configurations | |
x-operation: FetchOwnConfigurations | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
parameters: | |
- in: query | |
name: ids | |
description: Array of configuration ids you want to search | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
description: An configuration ID | |
responses: | |
"200": | |
description: An array of configurations with their related tags | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
id: | |
description: The id of this configuration | |
type: integer | |
minimum: 0 | |
example: 42 | |
tags: | |
type: array | |
description: The linked tags to this configuration | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
isValidated: | |
type: boolean | |
example: false | |
description: Is this tag validated or not | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
example: 42 | |
required: | |
- category_id | |
- isValidated | |
- version | |
required: | |
- name | |
- title | |
- id | |
- tags | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
description: Update a configuration | |
operationId: UpdateConfiguration | |
x-controller: configurations | |
x-operation: UpdateConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
tags: | |
description: An array of tags IDS | |
type: array | |
example: | |
- 42 | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
required: | |
- name | |
- tags | |
- type: object | |
properties: | |
id: | |
description: The id of this configuration | |
type: integer | |
minimum: 0 | |
example: 42 | |
required: | |
- id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
post: | |
description: Create a configuration | |
operationId: CreateConfiguration | |
x-controller: configurations | |
x-operation: CreateConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
tags: | |
description: An array of tags IDS | |
type: array | |
example: | |
- 42 | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
required: | |
- name | |
- tags | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
delete: | |
description: Delete a configuration | |
operationId: DeleteConfiguration | |
x-controller: configurations | |
x-operation: DeleteConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
id: | |
description: The id of the configuration you want to delete | |
type: integer | |
minimum: 0 | |
example: 42 | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/users: | |
get: | |
summary: List users | |
operationId: ListUsers | |
x-controller: users | |
x-operation: ListUsers | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
parameters: | |
- in: query | |
name: metadata | |
style: deepObject | |
schema: | |
type: object | |
description: Fields for pagination | |
properties: | |
page: | |
type: integer | |
description: Page number (start at 1) | |
minimum: 1 | |
default: 1 | |
example: 1 | |
size: | |
type: integer | |
minimum: 0 | |
description: Number of items by page | |
default: 10 | |
example: 10 | |
maximum: 50 | |
responses: | |
"200": | |
description: An list of Users with some metadata | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
currentPage: | |
type: integer | |
example: 1 | |
minimum: 1 | |
description: Current number of page | |
default: 1 | |
totalItems: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: How much items match the given criterias | |
totalPages: | |
type: integer | |
minimum: 0 | |
example: 5 | |
description: How much pages match the given criterias | |
pageSize: | |
type: integer | |
minimum: 0 | |
example: 10 | |
default: 10 | |
description: How many entries on each page | |
required: | |
- currentPage | |
- totalItems | |
- totalPages | |
- pageSize | |
data: | |
type: array | |
items: | |
allOf: | |
- $ref: "#/paths/~1auth~1me/get/responses/200/content/appli\ | |
cation~1json/schema/allOf/0" | |
- type: object | |
properties: | |
role: | |
$ref: "#/paths/~1auth~1me/get/responses/200/content/a\ | |
pplication~1json/schema/allOf/1/properties/role" | |
id: | |
type: integer | |
description: The UUID of this user | |
example: 42 | |
required: | |
- role | |
- id | |
required: | |
- metadata | |
- data | |
"/files/{file}": | |
parameters: | |
- name: file | |
in: path | |
description: The path to the file we want to access | |
example: someFile.zip | |
required: true | |
schema: | |
type: string | |
get: | |
summary: Download a stored file on the API | |
operationId: downloadFile | |
tags: | |
- guest | |
responses: | |
"200": | |
description: The file | |
content: | |
"*/*": | |
schema: | |
type: string | |
format: binary | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
components: | |
securitySchemes: | |
bearerAuth: | |
type: http | |
scheme: bearer | |
bearerFormat: JWT |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.0 | |
info: | |
description: API for Source Code | |
version: 1.0.0 | |
title: Source Code API | |
license: | |
name: GPL-3.0-or-later | |
url: https://choosealicense.com/licenses/gpl-3.0/ | |
servers: | |
- url: http://localhost:3000 | |
description: Internal staging server for testing | |
- url: http://api.example.com/v1 | |
description: Optional server description, e.g. Main (production) server | |
tags: | |
- name: guest | |
description: Everything a(n) visitor / not authentified user could do | |
- name: user | |
description: Everything an authentified user could do (more than a guest) | |
- name: admin | |
description: Everything an administrator could do (more than an user) | |
paths: | |
/auth/login: | |
post: | |
summary: Logs user into the system | |
operationId: signIn | |
x-controller: auth | |
x-operation: signIn | |
tags: | |
- guest | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
password: | |
type: string | |
format: password | |
example: "42" | |
required: | |
- password | |
responses: | |
"200": | |
description: A JSON containing the JWT Token and some information about the user | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
token: | |
type: string | |
description: The JWT Token | |
required: | |
- token | |
- type: object | |
description: Some basic information on this user | |
properties: | |
user: | |
type: object | |
properties: | |
fullName: | |
type: string | |
description: The full name of this user | |
example: Alexandre Dewit | |
minLength: 1 | |
maxLength: 50 | |
role: | |
type: string | |
enum: | |
- admin | |
- user | |
description: What kind of user are we ? | |
required: | |
- fullName | |
- role | |
required: | |
- user | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
message: | |
type: string | |
description: The main error message ( for example "Bad Request", | |
"Unauthorized", etc. ) | |
errors: | |
type: array | |
items: | |
type: object | |
description: Explanation about an error | |
required: | |
- message | |
- errors | |
/auth/register: | |
post: | |
summary: Creates a new user into the system | |
operationId: register | |
x-controller: auth | |
x-operation: register | |
tags: | |
- guest | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
password: | |
type: string | |
format: password | |
example: "42" | |
required: | |
- password | |
- type: object | |
properties: | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of this new user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/auth/me: | |
get: | |
summary: Fetch information about the current logged user | |
operationId: me | |
x-controller: users | |
x-operation: me | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
responses: | |
"200": | |
description: User data | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
- type: object | |
properties: | |
role: | |
type: string | |
enum: | |
- admin | |
- user | |
default: user | |
description: | | |
The type of user. Currently, 2 types are possibles : | |
1. user : The defaut ( an simple registered user ) | |
2. admin : User with additional credentials | |
id: | |
type: integer | |
description: The UUID of this user | |
example: 42 | |
required: | |
- role | |
- id | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/auth/update: | |
put: | |
summary: Update information about an user | |
description: > | |
Any user can freely any information about (him/her)self (except the | |
optional "id" / "role" fields ). | |
An admin can freely update any user and it is the only one that can use the "id" / "role" fields. | |
operationId: updateUser | |
x-controller: users | |
x-operation: updateUser | |
tags: | |
- user | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1auth~1me/get/responses/200/content/application~1\ | |
json/schema/allOf/0" | |
- type: object | |
properties: | |
password: | |
type: string | |
format: password | |
example: "42" | |
role: | |
$ref: "#/paths/~1auth~1me/get/responses/200/content/applicati\ | |
on~1json/schema/allOf/1/properties/role" | |
id: | |
type: integer | |
description: The UUID of this user. By default, it will take the one | |
of logged user | |
example: 42 | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/create_exercise: | |
post: | |
summary: Creates a new exercise into the system | |
description: > | |
Creates a new exercise into the system. | |
By default (if nothing specified), the exercise will be in state "DRAFT". | |
You are free to add new tags / keywords but you must add at least 3 validated tags. | |
The following restrictions are applied on simple user(s) (no restriction for admin): | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed for the field "state" : | |
- DRAFT | |
- PENDING | |
operationId: createSingleExercise | |
x-controller: exercises | |
x-operation: createSingleExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
multipart/form-data: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1api~1create_exercise/post/requestBody/content/ap\ | |
plication~1json/schema" | |
- type: object | |
properties: | |
exerciseFile: | |
type: string | |
format: binary | |
description: The sources of this exercise, in zip format | |
required: | |
- exerciseFile | |
encoding: | |
exerciseFile: | |
contentType: application/zip, application/x-zip-compressed, multipart/x-zip | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
"/api/exercises/{id}": | |
parameters: | |
- name: id | |
in: path | |
description: The exercise ID | |
required: true | |
schema: | |
type: integer | |
- name: includeOptions | |
in: query | |
description: To include additional properties when fetching exercise | |
style: deepObject | |
schema: | |
type: object | |
description: To include additional properties when fetching exercise(s) | |
properties: | |
includeCreator: | |
type: boolean | |
default: false | |
description: Must we include the creator of exercise(s) ? | |
includeMetrics: | |
type: boolean | |
default: true | |
description: Must we include the metrics of exercise(s) ? | |
includeDescription: | |
type: boolean | |
default: true | |
description: Must we include the description of exercise(s) ? | |
includeTags: | |
type: boolean | |
default: true | |
description: Must we include the tags of exercise(s) ? | |
get: | |
summary: Retrieve this specific exercise data | |
operationId: getExerciseByID | |
x-controller: exercises | |
x-operation: getExerciseByID | |
security: | |
- {} | |
- bearerAuth: [] | |
tags: | |
- guest | |
- user | |
responses: | |
"200": | |
description: Exercise data inside a JSON | |
content: | |
application/json: | |
schema: | |
allOf: | |
- allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
metrics: | |
type: object | |
description: The metrics of the exercise (present only if | |
includeMetrics is true) | |
properties: | |
votes: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: Number of votes for this exercise | |
avg_score: | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
description: The average score of this exercise | |
required: | |
- votes | |
- avg_score | |
tags: | |
type: array | |
description: The tags of the exercise (present only if | |
includeTags is true) | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category: | |
type: object | |
properties: | |
category_text: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of the Tag Category linked | |
with this tag | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category ID linked with this tag | |
required: | |
- category_text | |
- category_id | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. | |
Currently, 3 states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
required: | |
- category | |
- state | |
uniqueItems: true | |
creator: | |
allOf: | |
- type: object | |
description: The creator of the exercise (present only if | |
includeMetrics is true) | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
- type: object | |
properties: | |
vote: | |
type: number | |
minimum: 0 | |
example: 5 | |
description: If this endpoint was used by an authentified user, it | |
will fetch his/her vote if it exists | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Update this specific exercise data | |
description: > | |
Update this specific exercise data | |
You are free to add new tags / keywords but you **must** add at least 3 validated tags. | |
The following restrictions are applied on simple user(s) (no restriction for admin) : | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed for the field "state" : | |
- DRAFT | |
- PENDING | |
operationId: UpdateExercise | |
x-controller: exercises | |
x-operation: UpdateExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is | |
related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
- type: object | |
properties: | |
version: | |
type: integer | |
description: The version of this exercise (optimistic lock) | |
minimum: 0 | |
example: 42 | |
required: | |
- version | |
- type: object | |
properties: | |
removePreviousFile: | |
type: boolean | |
default: false | |
example: true | |
description: If set to true, the API will delete the previous file | |
when updating the exercise | |
multipart/form-data: | |
schema: | |
allOf: | |
- $ref: "#/paths/~1api~1exercises~1%7Bid%7D/put/requestBody/content\ | |
/application~1json/schema/allOf/0" | |
- type: object | |
description: If we want to also to change the sources zip file of this | |
exercise | |
properties: | |
exerciseFile: | |
type: string | |
format: binary | |
description: The sources of this exercise, in zip format | |
required: | |
- exerciseFile | |
encoding: | |
exerciseFile: | |
contentType: application/zip, application/x-zip-compressed, multipart/x-zip | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/export: | |
post: | |
operationId: ExportExercises | |
x-controller: exercises | |
x-operation: ExportExercises | |
description: > | |
To export exercises that match optional criteria. | |
The JSON result is compliant with the [format](https://github.com/SourceCodeOER/cli#what-is-the-format-of-the-json-object-) | |
of our [cli](https://github.com/SourceCodeOER/cli) which means that if you wish to reupload the exercises in the future, | |
it's simple as you just have to rely on the [cli](https://github.com/SourceCodeOER/cli) command "uploader". | |
Please consider the following facts before using it : | |
1. Don't forget to rename the key "categories" to "own_categories" | |
2. If you wish to upload them without their files, remove the property "file" in each exercise : | |
```js | |
let json_result = { /* ... */ }; | |
const exercisesWithoutFile = json_result["exercises"].map(exercise => { | |
delete exercise["file"] | |
return exercise; | |
}); | |
Object.assign(json_result, { "exercises": exercisesWithoutFile }); | |
``` | |
3. If you wish to upload them with their files, download their files and modify each property "file" according our [format](https://github.com/SourceCodeOER/cli#what-is-the-format-of-the-json-object-) | |
of our [cli](https://github.com/SourceCodeOER/cli). | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: false | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
orderBy: | |
description: > | |
If you wish to order the provided result, use this | |
parameter. | |
For example, if you wish to first sort by date descending then by title ascending, you could achieve that with : | |
``` | |
[ | |
{"field": "date", "value": "DESC"}, | |
{"field": "title", "value": "ASC"} | |
] | |
``` | |
type: array | |
maxItems: 6 | |
items: | |
type: object | |
properties: | |
field: | |
type: string | |
description: > | |
The field we want to use for sorting. Currently, you | |
have the following possibilities : | |
1. state : the state of the exercise | |
2. id : the id of the exercise | |
3. title : the title of the exercise | |
4. date : the date of the last modification of the exercise | |
5. avg_score : the average score of the exercise | |
6. vote_count : the number of voters for this exercise | |
enum: | |
- state | |
- id | |
- title | |
- date | |
- avg_score | |
- vote_count | |
value: | |
type: string | |
enum: | |
- ASC | |
- DESC | |
description: | | |
The order we want to sort the related field : | |
- ASC : ASCENDING sorting | |
- DESC : DESCENDING sorting | |
data: | |
type: object | |
description: Search criterias | |
properties: | |
title: | |
type: string | |
description: Something we want to find inside the title of exercises | |
maxLength: 100 | |
example: SINF2MS | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
format: int32 | |
example: 1 | |
- type: array | |
items: | |
type: integer | |
format: int32 | |
minItems: 1 | |
description: Tags search encoded in Conjunctive Normal Form. (for NOT | |
predicat, use a negative integer) | |
example: | |
- -1 | |
- - 2 | |
- 3 | |
user_ids: | |
type: array | |
description: Filter the exercises by their creators. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An user ID | |
uniqueItems: true | |
exercise_ids: | |
type: array | |
description: Filter the exercises by their ids. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An exercise ID | |
uniqueItems: true | |
vote: | |
description: Only take exercises that meet a given threshold | |
type: object | |
properties: | |
operator: | |
description: The operation we want to apply | |
type: string | |
enum: | |
- <= | |
- < | |
- ">=" | |
- ">" | |
value: | |
description: The threshold value | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
required: | |
- operator | |
- value | |
filterOptions: | |
type: object | |
description: | | |
To filter some properties when fetching exercise(s) | |
properties: | |
state: | |
type: array | |
description: Filter the exercises by their state. By default, no | |
filtering is done. | |
items: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
maxItems: 5 | |
tags: | |
type: array | |
description: Filter the tags linked to exercise by their state. By | |
default, no filtering is done. | |
items: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. Currently, 3 states | |
are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
maxItems: 3 | |
responses: | |
"200": | |
description: Exercises data inside a JSON | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercises: | |
description: The fetched exercises (with their tags) | |
type: array | |
items: | |
allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
tags: | |
type: array | |
description: The tags linked to this exercise | |
items: | |
type: object | |
properties: | |
text: | |
type: string | |
description: The text of this Tag | |
example: INGINIOUS | |
minLength: 1 | |
maxLength: 100 | |
category: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category of this tag | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. | |
Currently, 3 states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
required: | |
- state | |
- category | |
- text | |
required: | |
- tags | |
categories: | |
description: Map whose keys are the IDS of the categories and value | |
their text | |
type: object | |
example: | |
"1": source | |
"2": institution | |
"3": auteur | |
required: | |
- exercises | |
- categories | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/search: | |
post: | |
summary: Search exercises that matches criteria | |
tags: | |
- guest | |
operationId: searchExercises | |
x-controller: exercises | |
x-operation: searchExercises | |
requestBody: | |
required: false | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
orderBy: | |
description: > | |
If you wish to order the provided result, use this | |
parameter. | |
For example, if you wish to first sort by date descending then by title ascending, you could achieve that with : | |
``` | |
[ | |
{"field": "date", "value": "DESC"}, | |
{"field": "title", "value": "ASC"} | |
] | |
``` | |
type: array | |
maxItems: 6 | |
items: | |
type: object | |
properties: | |
field: | |
type: string | |
description: > | |
The field we want to use for sorting. Currently, | |
you have the following possibilities : | |
1. state : the state of the exercise | |
2. id : the id of the exercise | |
3. title : the title of the exercise | |
4. date : the date of the last modification of the exercise | |
5. avg_score : the average score of the exercise | |
6. vote_count : the number of voters for this exercise | |
enum: | |
- state | |
- id | |
- title | |
- date | |
- avg_score | |
- vote_count | |
value: | |
type: string | |
enum: | |
- ASC | |
- DESC | |
description: | | |
The order we want to sort the related field : | |
- ASC : ASCENDING sorting | |
- DESC : DESCENDING sorting | |
data: | |
type: object | |
description: Search criterias | |
properties: | |
title: | |
type: string | |
description: Something we want to find inside the title of | |
exercises | |
maxLength: 100 | |
example: SINF2MS | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
format: int32 | |
example: 1 | |
- type: array | |
items: | |
type: integer | |
format: int32 | |
minItems: 1 | |
description: Tags search encoded in Conjunctive Normal Form. (for | |
NOT predicat, use a negative integer) | |
example: | |
- -1 | |
- - 2 | |
- 3 | |
user_ids: | |
type: array | |
description: Filter the exercises by their creators. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An user ID | |
uniqueItems: true | |
exercise_ids: | |
type: array | |
description: Filter the exercises by their ids. | |
minItems: 1 | |
items: | |
type: integer | |
minimum: 0 | |
description: An exercise ID | |
uniqueItems: true | |
vote: | |
description: Only take exercises that meet a given threshold | |
type: object | |
properties: | |
operator: | |
description: The operation we want to apply | |
type: string | |
enum: | |
- <= | |
- < | |
- ">=" | |
- ">" | |
value: | |
description: The threshold value | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
required: | |
- operator | |
- value | |
filterOptions: | |
type: object | |
description: | | |
To filter some properties when fetching exercise(s) | |
properties: | |
state: | |
type: array | |
description: Filter the exercises by their state. By default, no | |
filtering is done. | |
items: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, | |
5 states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
maxItems: 5 | |
tags: | |
type: array | |
description: Filter the tags linked to exercise by their state. | |
By default, no filtering is done. | |
items: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. Currently, 3 | |
states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
maxItems: 3 | |
- type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
page: | |
type: integer | |
description: Page number (start at 1) | |
minimum: 1 | |
default: 1 | |
example: 1 | |
size: | |
type: integer | |
minimum: 0 | |
description: Number of items by page | |
default: 10 | |
example: 10 | |
maximum: 50 | |
includeOptions: | |
type: object | |
description: To include additional properties when fetching | |
exercise(s) | |
properties: | |
includeCreator: | |
type: boolean | |
default: false | |
description: Must we include the creator of exercise(s) ? | |
includeMetrics: | |
type: boolean | |
default: true | |
description: Must we include the metrics of exercise(s) ? | |
includeDescription: | |
type: boolean | |
default: true | |
description: Must we include the description of exercise(s) ? | |
includeTags: | |
type: boolean | |
default: true | |
description: Must we include the tags of exercise(s) ? | |
examples: | |
searchExample1: | |
description: Search the first 10 exercises that have 'Java' in their title | |
and have some specific tags ( 1 AND (2 OR 3 OR 4) ) | |
value: | |
data: | |
title: Java | |
tags: | |
- 1 | |
- - 2 | |
- 3 | |
- 4 | |
searchExample2: | |
description: Search the exercises on page 2 that have 'Java' in their title | |
but with specific tags ( (NOT 1) AND (2 OR 3) ) | |
value: | |
metadata: | |
page: 2 | |
size: 10 | |
data: | |
title: Java | |
tags: | |
- -1 | |
- - 2 | |
- 3 | |
responses: | |
"200": | |
description: An object that contains the results and additionnal information | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
currentPage: | |
type: integer | |
example: 1 | |
minimum: 1 | |
description: Current number of page | |
default: 1 | |
totalItems: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: How much items match the given criterias | |
totalPages: | |
type: integer | |
minimum: 0 | |
example: 5 | |
description: How much pages match the given criterias | |
pageSize: | |
type: integer | |
minimum: 0 | |
example: 10 | |
default: 10 | |
description: How many entries on each page | |
required: | |
- currentPage | |
- totalItems | |
- totalPages | |
- pageSize | |
data: | |
type: array | |
items: | |
allOf: | |
- allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this exercise | |
version: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
createdAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:18:31.090Z | |
description: Date of creation of this exercise | |
updatedAt: | |
type: string | |
format: date-time | |
example: 2019-12-22T15:19:33.473Z | |
description: Date of the latest update of this exercise | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. | |
Currently, 5 states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
file: | |
type: string | |
nullable: true | |
description: If not null, it is a uploaded file we can | |
download with the GET endpoint /files/{file} | |
example: sources-88af5adc-1837-11ea-8d71-362b9e155667.zip | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a | |
plateform | |
required: | |
- id | |
- version | |
- createdAt | |
- updatedAt | |
- state | |
- file | |
- url | |
- type: object | |
properties: | |
metrics: | |
type: object | |
description: The metrics of the exercise (present only if | |
includeMetrics is true) | |
properties: | |
votes: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: Number of votes for this exercise | |
avg_score: | |
type: number | |
minimum: 0 | |
maximum: 5 | |
example: 5 | |
description: The average score of this exercise | |
required: | |
- votes | |
- avg_score | |
tags: | |
type: array | |
description: The tags of the exercise (present only if | |
includeTags is true) | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category: | |
type: object | |
properties: | |
category_text: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of the Tag Category | |
linked with this tag | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The category ID linked with this | |
tag | |
required: | |
- category_text | |
- category_id | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. | |
Currently, 3 states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
required: | |
- category | |
- state | |
uniqueItems: true | |
creator: | |
allOf: | |
- type: object | |
description: The creator of the exercise (present only if | |
includeMetrics is true) | |
- type: object | |
properties: | |
email: | |
type: string | |
format: email | |
example: jy95@perdu.com | |
description: The email of the user | |
fullName: | |
type: string | |
example: Alexandre Dewit | |
description: The full name of the user | |
minLength: 1 | |
maxLength: 50 | |
required: | |
- fullName | |
required: | |
- metadata | |
- data | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags: | |
post: | |
summary: Submit a tag proposal | |
tags: | |
- user | |
operationId: submitTagProposal | |
x-controller: tags | |
x-operation: submitTagProposal | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Modify a Tag | |
tags: | |
- admin | |
operationId: updateTag | |
x-controller: tags | |
x-operation: updateTag | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. Currently, 3 states | |
are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
example: 42 | |
required: | |
- category_id | |
- state | |
- version | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
get: | |
summary: Retrieve all tags | |
tags: | |
- guest | |
operationId: getTags | |
x-controller: tags | |
x-operation: getTags | |
parameters: | |
- in: query | |
name: tags_ids | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
description: Only consider the given tag ID(S) | |
- in: query | |
name: categories_ids | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
description: Only consider the given tag categories ID(S) | |
- in: query | |
name: state | |
schema: | |
type: array | |
description: Filter the tags by their state. By default, no filtering is done. | |
items: | |
$ref: "#/paths/~1api~1export/post/responses/200/content/application~1\ | |
json/schema/properties/exercises/items/allOf/1/properties/tags/\ | |
items/properties/state" | |
maxItems: 3 | |
- in: query | |
name: title | |
schema: | |
type: string | |
description: Filter the tags by their text (case-insensitive comparison) | |
maxLength: 100 | |
responses: | |
"200": | |
description: An array of tag | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: "#/paths/~1api~1tags/put/requestBody/content/application~1j\ | |
son/schema" | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags_categories: | |
get: | |
summary: Retrieve only Tag categories | |
operationId: getTagCategories | |
x-controller: tags_categories | |
x-operation: getTagCategories | |
tags: | |
- guest | |
parameters: | |
- in: query | |
name: fetchStats | |
schema: | |
type: integer | |
enum: | |
- 0 | |
- 1 | |
description: If set to 1, it means that you enabled. Otherwise (0 or not | |
defined), you disabled it | |
description: If enabled, you can retrieve extra properties with the tag category | |
responses: | |
"200": | |
description: An array of tag categories | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
allOf: | |
- type: object | |
properties: | |
id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: The Id of this Tag_Category | |
category: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of this Tag_Category | |
required: | |
- id | |
- category | |
- type: object | |
description: "If queryParameter 'fetchStats' is set to 1, you can | |
retrieve the following count properties :" | |
properties: | |
total: | |
type: integer | |
description: The total number of tags under this tag category | |
minimum: 0 | |
total_validated: | |
type: integer | |
description: The total number of VALIDATED tags under this tag | |
category | |
minimum: 0 | |
total_unvalidated: | |
type: integer | |
description: The total number of NOT_VALIDATED tags under this | |
tag category | |
minimum: 0 | |
total_deprecated: | |
type: integer | |
description: The total number of DEPRECATED tags under this tag | |
category | |
minimum: 0 | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
summary: Update a Tag category | |
operationId: updateTagCategory | |
x-controller: tags_categories | |
x-operation: updateTagCategory | |
security: | |
- bearerAuth: [] | |
tags: | |
- admin | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1api~1tags_categories/get/responses/200/content/appli\ | |
cation~1json/schema/items/allOf/0" | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/tags_by_categories: | |
get: | |
summary: Retrieve Tag categories with their related tags | |
tags: | |
- guest | |
operationId: getTagCategoriesWithTags | |
x-controller: tags_categories | |
x-operation: getTagCategoriesWithTags | |
parameters: | |
- in: query | |
name: state | |
schema: | |
type: array | |
description: Filter the tags by their state. By default, no filtering is done. | |
items: | |
$ref: "#/paths/~1api~1export/post/responses/200/content/application~1\ | |
json/schema/properties/exercises/items/allOf/1/properties/tags/\ | |
items/properties/state" | |
maxItems: 3 | |
- in: query | |
name: onlySelected | |
schema: | |
type: array | |
description: If not empty, only consider the given tag categories ID(S). If | |
empty, no tag category is ignored | |
default: [] | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A Tag Category ID | |
responses: | |
"200": | |
description: An array of Tag category with their related tags | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
allOf: | |
- type: object | |
properties: | |
id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: The Id of this Tag_Category | |
category: | |
type: string | |
example: difficulty | |
minLength: 3 | |
maxLength: 100 | |
description: The text of this Tag_Category | |
required: | |
- id | |
- category | |
- type: object | |
properties: | |
tags: | |
type: array | |
description: An array of related tags to this Tag Category | |
minItems: 1 | |
uniqueItems: true | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. | |
Currently, 3 states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic | |
lock) | |
example: 42 | |
required: | |
- category_id | |
- state | |
- version | |
required: | |
- tags | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_exercises: | |
post: | |
summary: Creates multiple exercises into the system | |
description: > | |
Creates multiple exercises into the system | |
By default (if nothing specified), an exercise will be in state "DRAFT". | |
tags: | |
- admin | |
operationId: createMultipleExercises | |
x-controller: bulk | |
x-operation: createMultipleExercises | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
allOf: | |
- type: object | |
properties: | |
title: | |
type: string | |
example: A Super Exercise | |
minLength: 3 | |
maxLength: 100 | |
description: The title of this exercise | |
description: | |
type: string | |
maxLength: 5000 | |
example: ... | |
description: The preamble of this exercise | |
default: "" | |
required: | |
- title | |
- type: object | |
properties: | |
tags: | |
type: array | |
items: | |
oneOf: | |
- type: integer | |
minimum: 0 | |
description: A Tag ID ( already existent in database ) | |
- type: object | |
properties: | |
text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
category_id: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: the category id to which this tag is related | |
required: | |
- text | |
- category_id | |
description: Mixed array that contains existent tag(s) or not | |
uniqueItems: true | |
minItems: 3 | |
maxItems: 25 | |
url: | |
type: string | |
pattern: ^https?:\/\/[^\s$.?#].[^\s]*$ | |
example: https://inginious.info.ucl.ac.be/course/LEPL1402/Streams | |
nullable: true | |
description: If not null, the link to the exercise on a plateform | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 | |
states are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- tags | |
multipart/form-data: | |
schema: | |
type: object | |
properties: | |
exercisesData: | |
$ref: "#/paths/~1api~1bulk~1create_exercises/post/requestBody/con\ | |
tent/application~1json/schema" | |
files: | |
type: array | |
description: The sources of the exercises, each in zip format | |
minItems: 1 | |
items: | |
type: string | |
format: binary | |
description: The source of an exercise, in zip format | |
filesMapping: | |
type: array | |
description: Mapping between the given file (to find out which data | |
belong to exercise) | |
minItems: 1 | |
items: | |
type: object | |
properties: | |
filename: | |
type: string | |
description: The name of the given source file | |
example: file1.zip | |
exercise: | |
type: integer | |
description: The location of the related exercise in the | |
exercisesData array | |
required: | |
- filename | |
- exercise | |
required: | |
- exercisesData | |
- files | |
- filesMapping | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_or_find_tag_categories: | |
post: | |
summary: Creates or Find tag categories | |
x-controller: bulk | |
x-operation: createOrFindTagCategories | |
tags: | |
- admin | |
operationId: createOrFindTagCategories | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
oneOf: | |
- type: string | |
description: The name of the Tag Category | |
example: author | |
- type: object | |
description: Category to add, under one that already exists | |
properties: | |
text: | |
type: string | |
description: The name of the Tag Category | |
example: author | |
minLength: 3 | |
maxLength: 100 | |
category: | |
type: integer | |
format: int32 | |
minimum: 0 | |
description: The ID of the Tag Category parent | |
required: | |
- text | |
- category | |
responses: | |
"200": | |
description: An array of tag categories | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: "#/paths/~1api~1tags_categories/get/responses/200/content/a\ | |
pplication~1json/schema/items/allOf/0" | |
uniqueItems: true | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/modify_exercises_status: | |
put: | |
summary: Change the status of given exercises | |
description: > | |
Change the status of given exercises. | |
The following restrictions are applied on simple user(s) (no restriction for admin): | |
1. He/She can only modify his/her own exercises | |
2. Only the following states are allowed : | |
- DRAFT | |
- PENDING | |
- ARCHIVED | |
operationId: ChangeExercisesStatus | |
x-controller: bulk | |
x-operation: ChangeExercisesStatus | |
tags: | |
- admin | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercises: | |
type: array | |
description: An array of exercises IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: An exercise ID | |
state: | |
type: string | |
enum: | |
- DRAFT | |
- PENDING | |
- VALIDATED | |
- NOT_VALIDATED | |
- ARCHIVED | |
example: PENDING | |
description: > | |
Status of the exercise into the system. Currently, 5 states | |
are possibles : | |
1. DRAFT : The default state (for example when an exercise is inserted into the system) | |
2. PENDING : When an exercise is ready for review | |
3. VALIDATED : When an exercise is validated by an admin | |
4. NOT_VALIDATED : When an exercise is refused by an admin | |
5. ARCHIVED : When an exercise is archived / soft deleted | |
required: | |
- exercises | |
- state | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_exercises: | |
delete: | |
summary: Delete given exercises | |
description: > | |
Permanently remove from system the given exercises. (No way to retrieve | |
them after this) | |
Otherwise, if you simply want to soft delete/hide these exercises, use [this endpoint](#operation/ChangeExercisesStatus) to change their status to ARCHIVED. | |
operationId: DeleteExercises | |
x-controller: bulk | |
x-operation: DeleteExercises | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of exercises IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: An exercise ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_tags: | |
delete: | |
summary: Delete given tags | |
description: Delete given tags. | |
operationId: DeleteTags | |
x-controller: bulk | |
x-operation: DeleteTags | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of tags IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A tag ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/delete_tags_categories: | |
delete: | |
summary: Delete given tags categories | |
description: Delete given tags categories. | |
operationId: DeleteTagCategories | |
x-controller: bulk | |
x-operation: DeleteTagCategories | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
description: An array of tag category IDs | |
minItems: 1 | |
uniqueItems: true | |
items: | |
type: integer | |
minimum: 0 | |
example: 42 | |
description: A tag category ID | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/bulk/create_tags: | |
post: | |
summary: Creates multiple tags into the system | |
description: > | |
Creates multiple tags into the system. | |
Warning : the "state" property can only be used by authorized people (no simple user can use it) | |
tags: | |
- user | |
operationId: createMultipleTags | |
x-controller: bulk | |
x-operation: createMultipleTags | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: array | |
minItems: 1 | |
items: | |
allOf: | |
- $ref: "#/paths/~1api~1tags/post/requestBody/content/application\ | |
~1json/schema" | |
- type: object | |
properties: | |
state: | |
$ref: "#/paths/~1api~1export/post/responses/200/content/app\ | |
lication~1json/schema/properties/exercises/items/allO\ | |
f/1/properties/tags/items/properties/state" | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/vote_for_exercise: | |
post: | |
summary: Vote (or update the vote) of the current logged user for given exercise | |
operationId: voteForExercise | |
x-controller: exercises | |
x-operation: voteForExercise | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
exercise_id: | |
type: integer | |
minimum: 0 | |
description: The ID of the exercise we want to vote / modify a vote | |
example: 42 | |
score: | |
type: number | |
format: double | |
minimum: 0 | |
example: 5 | |
description: The score we want to give to this exercise | |
required: | |
- score | |
- exercise_id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/configurations: | |
get: | |
description: Get all configurations of the current logged user | |
operationId: FetchOwnConfigurations | |
x-controller: configurations | |
x-operation: FetchOwnConfigurations | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
parameters: | |
- in: query | |
name: ids | |
description: Array of configuration ids you want to search | |
schema: | |
type: array | |
items: | |
type: integer | |
minimum: 0 | |
description: An configuration ID | |
responses: | |
"200": | |
description: An array of configurations with their related tags | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
id: | |
description: The id of this configuration | |
type: integer | |
minimum: 0 | |
example: 42 | |
tags: | |
type: array | |
description: The linked tags to this configuration | |
items: | |
allOf: | |
- type: object | |
properties: | |
tag_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: The Id of this Tag | |
tag_text: | |
type: string | |
example: easy | |
minLength: 1 | |
maxLength: 100 | |
description: The text of this Tag | |
required: | |
- tag_id | |
- tag_text | |
- type: object | |
properties: | |
category_id: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: the category id to which it is related | |
state: | |
type: string | |
enum: | |
- NOT_VALIDATED | |
- VALIDATED | |
- DEPRECATED | |
example: DEPRECATED | |
description: > | |
Status of the tag into the system. Currently, | |
3 states are possibles : | |
1. NOT_VALIDATED : The default state ( for example when an exercise is inserted into the system) | |
2. VALIDATED : When a tag is officially recognized | |
3. DEPRECATED : When a tag should not be used anymore | |
version: | |
type: integer | |
minimum: 0 | |
description: The version of this exercise (optimistic lock) | |
example: 42 | |
required: | |
- category_id | |
- state | |
- version | |
required: | |
- name | |
- title | |
- id | |
- tags | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
put: | |
description: Update a configuration | |
operationId: UpdateConfiguration | |
x-controller: configurations | |
x-operation: UpdateConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
allOf: | |
- type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
tags: | |
description: An array of tags IDS | |
type: array | |
example: | |
- 42 | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
required: | |
- name | |
- tags | |
- type: object | |
properties: | |
id: | |
description: The id of this configuration | |
type: integer | |
minimum: 0 | |
example: 42 | |
required: | |
- id | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
post: | |
description: Create a configuration | |
operationId: CreateConfiguration | |
x-controller: configurations | |
x-operation: CreateConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
name: | |
description: The name of this configuration | |
type: string | |
example: All Java exercises | |
title: | |
description: The used title for search | |
type: string | |
example: "[LSINF1252]" | |
maxLength: 100 | |
minLength: 0 | |
tags: | |
description: An array of tags IDS | |
type: array | |
example: | |
- 42 | |
items: | |
type: integer | |
minimum: 0 | |
minItems: 1 | |
required: | |
- name | |
- tags | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
delete: | |
description: Delete a configuration | |
operationId: DeleteConfiguration | |
x-controller: configurations | |
x-operation: DeleteConfiguration | |
tags: | |
- user | |
security: | |
- bearerAuth: [] | |
requestBody: | |
required: true | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
id: | |
description: The id of the configuration you want to delete | |
type: integer | |
minimum: 0 | |
example: 42 | |
responses: | |
"200": | |
description: OK | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
/api/users: | |
get: | |
summary: List users | |
operationId: ListUsers | |
x-controller: users | |
x-operation: ListUsers | |
tags: | |
- admin | |
security: | |
- bearerAuth: [] | |
parameters: | |
- in: query | |
name: metadata | |
style: deepObject | |
schema: | |
type: object | |
description: Fields for pagination | |
properties: | |
page: | |
type: integer | |
description: Page number (start at 1) | |
minimum: 1 | |
default: 1 | |
example: 1 | |
size: | |
type: integer | |
minimum: 0 | |
description: Number of items by page | |
default: 10 | |
example: 10 | |
maximum: 50 | |
responses: | |
"200": | |
description: An list of Users with some metadata | |
content: | |
application/json: | |
schema: | |
type: object | |
properties: | |
metadata: | |
type: object | |
description: Fields for pagination | |
properties: | |
currentPage: | |
type: integer | |
example: 1 | |
minimum: 1 | |
description: Current number of page | |
default: 1 | |
totalItems: | |
type: integer | |
example: 42 | |
minimum: 0 | |
description: How much items match the given criterias | |
totalPages: | |
type: integer | |
minimum: 0 | |
example: 5 | |
description: How much pages match the given criterias | |
pageSize: | |
type: integer | |
minimum: 0 | |
example: 10 | |
default: 10 | |
description: How many entries on each page | |
required: | |
- currentPage | |
- totalItems | |
- totalPages | |
- pageSize | |
data: | |
type: array | |
items: | |
allOf: | |
- $ref: "#/paths/~1auth~1me/get/responses/200/content/appli\ | |
cation~1json/schema/allOf/0" | |
- type: object | |
properties: | |
role: | |
$ref: "#/paths/~1auth~1me/get/responses/200/content/a\ | |
pplication~1json/schema/allOf/1/properties/role" | |
id: | |
type: integer | |
description: The UUID of this user | |
example: 42 | |
required: | |
- role | |
- id | |
required: | |
- metadata | |
- data | |
"/files/{file}": | |
parameters: | |
- name: file | |
in: path | |
description: The path to the file we want to access | |
example: someFile.zip | |
required: true | |
schema: | |
type: string | |
get: | |
summary: Download a stored file on the API | |
operationId: downloadFile | |
tags: | |
- guest | |
responses: | |
"200": | |
description: The file | |
content: | |
"*/*": | |
schema: | |
type: string | |
format: binary | |
default: | |
description: "Whatever error : 4XX - Client error (Bad Request, Unauthorized, | |
etc.) , 5XX - Server error" | |
content: | |
application/json: | |
schema: | |
$ref: "#/paths/~1auth~1login/post/responses/default/content/applica\ | |
tion~1json/schema" | |
components: | |
securitySchemes: | |
bearerAuth: | |
type: http | |
scheme: bearer | |
bearerFormat: JWT |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment