Source Code API (1.0.0)

Download OpenAPI specification:Download

License: GPL-3.0-or-later

API for Source Code

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

guest

Everything a(n) visitor / not authentified user could do

Logs user into the system

Request Body schema: application/json
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "email": "jy95@perdu.com",
  • "password": "42"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Creates a new user into the system

Request Body schema: application/json
email
required
string <email>
password
required
string <password>
fullName
required
string [ 1 .. 50 ] characters

The full name of this new user

Responses

Request samples

Content type
application/json
{
  • "email": "jy95@perdu.com",
  • "password": "42",
  • "fullName": "Alexandre Dewit"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Verify if given JWT token is valid (and not expired)

Request Body schema: application/json
token
required
string^[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-...

An JWT Token string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Retrieve this specific exercise data

Authorizations:
path Parameters
id
required
integer

The exercise ID

query Parameters
object (IncludeOptions)

To include additional properties when fetching exercise

Responses

Response samples

Content type
application/json
{
  • "title": "A Super Exercise",
  • "description": "...",
  • "id": 42,
  • "version": 42,
  • "createdAt": "2019-12-22T15:18:31.090Z",
  • "updatedAt": "2019-12-22T15:19:33.473Z",
  • "state": "PENDING",
  • "file": "sources-88af5adc-1837-11ea-8d71-362b9e155667.zip",
  • "metrics": {
    },
  • "tags": [
    ],
  • "creator": {
    },
  • "vote": 5
}

Search exercises that matches criteria

Request Body schema: application/json
Array of objects <= 6 items

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"}
  ]
object (SearchDataCriterias)

Search criterias

object (FilteringOptions)

To filter some properties when fetching exercise(s)

object (PaginationCriterias)

Fields for pagination

object (IncludeOptions)

To include additional properties when fetching exercise(s)

Responses

Request samples

Content type
application/json
Example

Search the first 10 exercises that have 'Java' in their title and have some specific tags ( 1 AND (2 OR 3 OR 4) )

{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ]
}

Retrieve all tags

query Parameters
tags_ids
Array of integers non-empty

Only consider the given tag ID(S)

categories_ids
Array of integers non-empty

Only consider the given tag categories ID(S)

state
Array of strings (TagState) <= 4 items
Items Enum: "NOT_VALIDATED" "VALIDATED" "DEPRECATED" "PENDING"
Example: state=DEPRECATED

Filter the tags by their state. By default, no filtering is done.

title
string <= 100 characters

Filter the tags by their text (case-insensitive comparison)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve only Tag categories

query Parameters
fetchStats
integer
Enum: 0 1

If enabled, you can retrieve extra properties with the tag category

category_ids
Array of integers

Take only the given categories

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Tag categories with their related tags

query Parameters
state
Array of strings (TagState) <= 4 items
Items Enum: "NOT_VALIDATED" "VALIDATED" "DEPRECATED" "PENDING"
Example: state=DEPRECATED

Filter the tags by their state. By default, no filtering is done.

onlySelected
Array of integers unique
Default: []
Example: onlySelected=42

If not empty, only consider the given tag categories ID(S). If empty, no tag category is ignored

countStates
Array of strings (State) <= 5 items
Items Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"
Example: countStates=PENDING

If not empty, only consider the given exercise state(s) to compute the field "total" inside each tag.
If empty, every exercise state will be considered for the sum.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download a stored file on the API

path Parameters
file
required
string
Example: someFile.zip

The path to the file we want to access

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

user

Everything an authentified user could do (more than a guest)

Fetch information about the current logged user

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "email": "jy95@perdu.com",
  • "fullName": "Alexandre Dewit",
  • "role": "user",
  • "id": 42
}

Update information about an user

Any user can freely any information about (him/her)self (except the optional "id" / "role" fields ).
An super admin can freely update any user and it is the only one that can use the "id" / "role" fields.

Authorizations:
Request Body schema: application/json
fullName
string [ 1 .. 50 ] characters

The full name of the user

password
string <password>
role
string (Roles)
Default: "user"
Enum: "super_admin" "admin" "user"

The type of user. Currently, 3 types are possibles :

  1. user : The defaut ( an simple registered user )
  2. admin : User with additional credentials
  3. super_admin : More powerful than an admin
id
integer

The UUID of this user. By default, it will take the one of logged user

Responses

Request samples

Content type
application/json
{
  • "fullName": "Alexandre Dewit",
  • "password": "42",
  • "role": "user",
  • "id": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Creates a new exercise into the system

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
  3. He/She can't use the field "state" inside an tag object of "tags" array
Authorizations:
Request Body schema:
title
required
string [ 3 .. 100 ] characters

The title of this exercise

description
string <= 5000 characters
Default: ""

The preamble of this exercise

required
Array of integers or TagProposalWithState (object) [ 3 .. 25 ] items unique

Mixed array that contains existent tag(s) or not

url
string Nullable ^https?:\/\/[^\s$.?#].[^\s]*$

If not null, the link to the exercise on a plateform

state
string (State)
Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"

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

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Retrieve this specific exercise data

Authorizations:
path Parameters
id
required
integer

The exercise ID

query Parameters
object (IncludeOptions)

To include additional properties when fetching exercise

Responses

Response samples

Content type
application/json
{
  • "title": "A Super Exercise",
  • "description": "...",
  • "id": 42,
  • "version": 42,
  • "createdAt": "2019-12-22T15:18:31.090Z",
  • "updatedAt": "2019-12-22T15:19:33.473Z",
  • "state": "PENDING",
  • "file": "sources-88af5adc-1837-11ea-8d71-362b9e155667.zip",
  • "metrics": {
    },
  • "tags": [
    ],
  • "creator": {
    },
  • "vote": 5
}

Update this specific exercise data

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
  3. He/She can't use the field "state" inside an tag object of "tags" array
Authorizations:
path Parameters
id
required
integer

The exercise ID

query Parameters
object (IncludeOptions)

To include additional properties when fetching exercise

Request Body schema:
title
required
string [ 3 .. 100 ] characters

The title of this exercise

description
string <= 5000 characters
Default: ""

The preamble of this exercise

required
Array of integers or TagProposalWithState (object) [ 3 .. 25 ] items unique

Mixed array that contains existent tag(s) or not

url
string Nullable ^https?:\/\/[^\s$.?#].[^\s]*$

If not null, the link to the exercise on a plateform

state
string (State)
Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"

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
version
required
integer >= 0

The version of this exercise (optimistic lock)

removePreviousFile
boolean
Default: false

If set to true, the API will delete the previous file when updating the exercise

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Submit a tag proposal

Authorizations:
Request Body schema: application/json
text
required
string [ 1 .. 100 ] characters

The text of this Tag

category_id
required
integer >= 0

the category id to which this tag is related

Responses

Request samples

Content type
application/json
{
  • "text": "easy",
  • "category_id": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Change the status of given exercises

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
Authorizations:
Request Body schema: application/json
exercises
required
Array of integers non-empty unique

An array of exercises IDs

state
required
string (State)
Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"

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

Responses

Request samples

Content type
application/json
{
  • "exercises": [
    ],
  • "state": "PENDING"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Creates multiple tags into the system

Creates multiple tags into the system.

Warning : the "state" property can only be used by authorized people (no simple user can use it)

Authorizations:
Request Body schema: application/json
Array ()
text
required
string [ 1 .. 100 ] characters

The text of this Tag

category_id
required
integer >= 0

the category id to which this tag is related

state
string (TagState)
Enum: "NOT_VALIDATED" "VALIDATED" "DEPRECATED" "PENDING"

Status of the tag into the system. Currently, 4 states are possibles :

  1. NOT_VALIDATED : When a tag is officially not recognized
  2. PENDING : The default state ( for example when an exercise is inserted into the system)
  3. DEPRECATED : When a tag should not be used anymore
  4. VALIDATED : When a tag is officially recognized

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Vote (or update the vote) of the current logged user for given exercise

Authorizations:
Request Body schema: application/json
exercise_id
required
integer >= 0

The ID of the exercise we want to vote / modify a vote

score
required
number <double> >= 0

The score we want to give to this exercise

Responses

Request samples

Content type
application/json
{
  • "exercise_id": 42,
  • "score": 5
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

FetchOwnConfigurations

Get all configurations of the current logged user

Authorizations:
query Parameters
ids
Array of integers

Array of configuration ids you want to search

Responses

Response samples

Content type
application/json
[
  • {
    }
]

UpdateConfiguration

Update a configuration

Authorizations:
Request Body schema: application/json
name
required
string

The name of this configuration

title
string [ 0 .. 100 ] characters

The used title for search

tags
Array of integers

An array of tags IDS

id
required
integer >= 0

The id of this configuration

Responses

Request samples

Content type
application/json
{
  • "name": "All Java exercises",
  • "title": "[LSINF1252]",
  • "tags": [
    ],
  • "id": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

CreateConfiguration

Create a configuration

Authorizations:
Request Body schema: application/json
name
required
string

The name of this configuration

title
string [ 0 .. 100 ] characters

The used title for search

tags
Array of integers

An array of tags IDS

Responses

Request samples

Content type
application/json
{
  • "name": "All Java exercises",
  • "title": "[LSINF1252]",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

DeleteConfiguration

Delete a configuration

Authorizations:
Request Body schema: application/json
id
integer >= 0

The id of the configuration you want to delete

Responses

Request samples

Content type
application/json
{
  • "id": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

admin

Everything an administrator could do (more than an user)

ExportExercises

To export exercises that match optional criteria.

The JSON result is compliant with the format of our 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 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 :

     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 of our cli.

Authorizations:
Request Body schema: application/json
Array of objects <= 6 items

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"}
  ]
object (SearchDataCriterias)

Search criterias

object (FilteringOptions)

To filter some properties when fetching exercise(s)

Responses

Request samples

Content type
application/json
{
  • "orderBy": [
    ],
  • "data": {
    },
  • "filterOptions": {
    }
}

Response samples

Content type
application/json
{
  • "exercises": [
    ],
  • "categories": {
    }
}

Modify a Tag

Authorizations:
Request Body schema: application/json
tag_id
required
integer >= 0

The Id of this Tag

tag_text
required
string [ 1 .. 100 ] characters

The text of this Tag

category_id
required
integer >= 0

the category id to which it is related

state
required
string (TagState)
Enum: "NOT_VALIDATED" "VALIDATED" "DEPRECATED" "PENDING"

Status of the tag into the system. Currently, 4 states are possibles :

  1. NOT_VALIDATED : When a tag is officially not recognized
  2. PENDING : The default state ( for example when an exercise is inserted into the system)
  3. DEPRECATED : When a tag should not be used anymore
  4. VALIDATED : When a tag is officially recognized
version
required
integer >= 0

The version of this exercise (optimistic lock)

Responses

Request samples

Content type
application/json
{
  • "tag_id": 42,
  • "tag_text": "easy",
  • "category_id": 42,
  • "state": "DEPRECATED",
  • "version": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Update a Tag category

Authorizations:
Request Body schema: application/json
id
required
integer >= 0

The Id of this Tag_Category

category
required
string [ 3 .. 100 ] characters

The text of this Tag_Category

Responses

Request samples

Content type
application/json
{
  • "id": 42,
  • "category": "difficulty"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Creates multiple exercises into the system

Creates multiple exercises into the system By default (if nothing specified), an exercise will be in state "DRAFT".

Authorizations:
Request Body schema:
Array ()
title
required
string [ 3 .. 100 ] characters

The title of this exercise

description
string <= 5000 characters
Default: ""

The preamble of this exercise

required
Array of integers or TagProposalWithState (object) [ 3 .. 25 ] items unique

Mixed array that contains existent tag(s) or not

url
string Nullable ^https?:\/\/[^\s$.?#].[^\s]*$

If not null, the link to the exercise on a plateform

state
string (State)
Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"

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

Responses

Request samples

Content type
[]

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Creates or Find tag categories

Authorizations:
Request Body schema: application/json
Array ()
One of
string

The name of the Tag Category

Responses

Request samples

Content type
application/json
[
  • "author"
]

Response samples

Content type
application/json
[
  • {
    }
]

Change the status of given exercises

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
Authorizations:
Request Body schema: application/json
exercises
required
Array of integers non-empty unique

An array of exercises IDs

state
required
string (State)
Enum: "DRAFT" "PENDING" "VALIDATED" "NOT_VALIDATED" "ARCHIVED"

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

Responses

Request samples

Content type
application/json
{
  • "exercises": [
    ],
  • "state": "PENDING"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

List users

Authorizations:
query Parameters
object (PaginationCriterias)

Fields for pagination

roles
Array of strings (Roles) <= 3 items unique
Default: []
Items Enum: "super_admin" "admin" "user"

If not empty, only consider the given user role(s). If empty, no user role is ignored

fullName
string [ 1 .. 100 ] characters
email
string <email> [ 1 .. 100 ] characters

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": [
    ]
}

super_admin

Everything an administrator could do (more than an admin)

Update information about an user

Any user can freely any information about (him/her)self (except the optional "id" / "role" fields ).
An super admin can freely update any user and it is the only one that can use the "id" / "role" fields.

Authorizations:
Request Body schema: application/json
fullName
string [ 1 .. 50 ] characters

The full name of the user

password
string <password>
role
string (Roles)
Default: "user"
Enum: "super_admin" "admin" "user"

The type of user. Currently, 3 types are possibles :

  1. user : The defaut ( an simple registered user )
  2. admin : User with additional credentials
  3. super_admin : More powerful than an admin
id
integer

The UUID of this user. By default, it will take the one of logged user

Responses

Request samples

Content type
application/json
{
  • "fullName": "Alexandre Dewit",
  • "password": "42",
  • "role": "user",
  • "id": 42
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Delete given exercises

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 to change their status to ARCHIVED.

Authorizations:
Request Body schema: application/json
Array ()
integer >= 0

An exercise ID

Responses

Request samples

Content type
application/json
[
  • 42
]

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Delete given tags

Delete given tags.

Authorizations:
Request Body schema: application/json
Array ()
integer >= 0

A tag ID

Responses

Request samples

Content type
application/json
[
  • 42
]

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}

Delete given tags categories

Delete given tags categories.

Authorizations:
Request Body schema: application/json
Array ()
integer >= 0

A tag category ID

Responses

Request samples

Content type
application/json
[
  • 42
]

Response samples

Content type
application/json
{
  • "message": "string",
  • "errors": [
    ]
}