# RaidUT Mobile Application : API Endpoints

# Authentication
## POST /auth/login

### Parameters
- login (string)
- password (string)

### Return values
- session_token (string)
- event_id (int)

{
    session_token: 'abc123',
    event_id: 2
}

### Error handling
- 401 : If no match for the credentials

### Description
Use this endpoint to authenticate a user. It will check if there's a match for the parameters in the database and return a permission level and a session token if true.

## GET /auth/verify_token

### Parameters
- session_token (string)

### Return values
- session_token (string)
- permission? ('organisateur'|'participant')

{
    session_token: 'abc123',
    permission: 'organisateur'
}

### Description
Use this endpoint to check if the session token is registered by the server as as authentified user. This should be done every time the user tries to access or edit authentified data. Else, it will return an empty string as a session_token and no permission level.

## POST /auth/logout

### Parameters
- session_token (string)

### Error handling
- 404 : If session token wasn't found on the server

### Description
Use this endpoint to delete the session token and effectively log a user out.

# User

## GET /user

### Parameters
- bibNumber (number)

### Return values
- array of object

{
    team: "Equipe A",
    ranking: [
        {
            event_name: '',
            rank : 123,
            time : '01:23:45',
        },
        ...
    ]
}

### Error handling
- 404 : If dossard number wasn't found in the database

### Description
Use this endpoint to get information about a user.

## POST /user/start-event

### Parameters
- dossard (number)
- session_token (string) : token of the user logging the start of the event
- event_id (number)

### Error handling
- 400 : If the participant associated with the dossard number already started this event
- 403 : If the user associated with the provided session_token doesn't have a 'organisateur' permission level
- 404 : If dossard number or event_id wasn't found in the database

### Description
Use this endpoint to register that a user started an event.

## POST /user/complete-event

### Parameters
- dossard (number)
- session_token (string) : token of the user logging the completion of the event
- event_id (number)
- additional_scores? (object) : object containing all additionnal scores from event

### Error handling
- 400 : If the participant associated with the dossard number already completed this event
- 403 : If the user associated with the provided session_token doesn't have a 'organisateur' permission level
- 404 : If dossard number or event_id wasn't found in the database

### Description
Use this endpoint to register that a user started an event.

# Events

## GET /event

### Parameters
- event_id (number)

### Return values
- event_id (number)
- name (string)

### Description
Use this endpoint to get information about an event.

## GET /event/list

### Return values
- events (array of objects)

[
    {
        id: 1,
        name: '',
        ...
    },
    {
        id: 2,
        name: '',
        ...
    },
    ...
]

### Description
Use this endpoint to get a list of all the events

## GET /event/ranking

### Parameters
- team_nbr (number)

### Return values
- ranking (array of array of object)

[
    [
        {
            team_name: '',
            score: 12,
        },
        {
            team_name: '',
            score : 5
            ...
        },
        ...
    ],
    [
        ...
    ],
    ...
]

### Error handling
- 404 : event_id wasn't found in database

### Description
Use this endpoint to get the ranking for an event. Returns all teams' name and score ranked by score.

## POST event/ranking

### Parameters
- isDuo (bool)
- events (array of ids)

### Return values
- Array of events with name and ranking

[
    {
        name: "Tir à l'arc",
        ranking: [
            {
              team_name: 'Equipe A',
              score: 326
            },
            {
              team_name: 'Equipe B',
              score: 287,
            },
            {
              team_name: 'Equipe C',
              score: 254,
            }
        ]
    },
    {
      name: "Course d'orientation",
      ranking: [
        {
          team_name: 'Equipe A',
          score: 187,
        },
        {
          team_name: 'Equipe B',
          score: 90,
        },
      ],
    },
]

### Description
Use this endpoint to get global ranking for every duos/trios in requested events

## POST event/ranking/last

### Parameters
- isDuo (bool)

### Return values

{
  id: 5,
  name: "Course d'orientation",
  ranking: [
    {
      team_name: 'Equipe A',
      score: 187,
    },
    {
      team_name: 'Equipe B',
      score: 90,
    },
  ],
},

### Description
Get id, name and ranking for latest event with results