Skip to content

Documentation API REST

Jump to bottom
ylked edited this page Oct 23, 2023 · 1 revision

[[TOC]]

Exemple

GET/POST

/<endpoint>
Description
Conditions
Paramètres 
{
  "param-n": "a query parameter",
  ...
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "result1": "value1",
    "result2": "value2",
    ...
  },
}
Echec 
{
  "success": false,
  "status": 4xx,
  "error": "status code title",
  "message": "error description"
}

Authentification des requêtes

Sur les endpoints sécurisés (icône 🔐 ), il est nécessaire de fournir un token d'authentification valable. Celui-ci peut être obtenu sur /login à l'aide des informations d'authentification classiques (nom d'utilisateur/e-mail + mot de passe).

Les tokens d'authentification expirent après 120 minutes.

Ce token doit être spécifié dans le header de la requête, dans le champ Authorization. Si le token n'est pas/plus valable, le serveur répond avec le code 401 UNAUTHORIZED. Il est alors nécessaire de se reconnecter.

Il est possible de vérifier si un token a expiré sur la route /check/token/ :

Vérifier si le token a expiré

GET (:closed_lock_with_key:)

/token/check
Description Permet de vérifier si un token a expiré.
Conditions Aucune.
Paramètres Aucun.
Réussite 
{
  "success" : true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "valid": true/false,
  }
}
Echec N/A

Code d'erreurs communs

Réponse en cas de token invalide

{
  "success": false,
  "status": 401,
  "error": "UNAUTHORIZED",
  "message": "Invalid token"
}

Pour des raisons de simplification, les cas d'échec dû au token invalide ne sont pas précisés dans la documentation ci-dessous.

Réponse en cas de paramètres manquants ou payload malformé

Si un paramètre requis est manquant ou si le payload est malformé (par exemple JSON invalide), le serveur renvoie le code 400 BAD REQUEST.

{
  "success": false,
  "status": 400,
  "error": "BAD REQUEST",
  "message": "
    * Invalid JSON 
    * Missing required parameter <param> "
}

Inscription et authentification

Connexion

La connexion permet d'obtenir un nouveau token d'authentification afin d'effectuer des requêtes sur les endpoints sécurisés (qui nécessitent une connexion valide).

POST

/login
Description Génération d'un nouveau token d'authentification.
Conditions Aucune.
Paramètres 
{
  "id": "<username> or <email>",
  "password": "<password>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null
  "message": "Login successful. New auth token has been issued."
  "content":
  {
    "token": "<new api token>",
    "expires_at": "<expiration timestamp>",
    "verified": <true>/<false>
  },
}
Echec 
{
  "success": false,
  "status": 401,
  "error": "UNAUTHORIZED",
  "message": "incorrect login informations"
}

Déconnexion

POST 🔐

/logout
Description Déconnexion de l'application et suppression (invalidation) du token d'authentification
Conditions Token existant et valide.
Paramètres Aucun.
Réussite 
{
  "success": true
  "status": 200, 
  "error": null,
  "message": "Logout successful"
}
Echec N/A

Inscription

POST

/register
Description Inscription à l'application
Conditions Aucune.
Paramètres 
{
  "username": "",
  "email": "",
  "password": ""
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "The account has been successfully created",
  "content": 
  {
    "token": "<new token>",
    "expires_at": "<token expiration timestamp>",
    "verified": false
  },
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "
    * Username already taken / 
    * Username contains forbidden characters / 
    * E-mail format is invalid / 
    * Password is too weak / 
    * Password contains forbidden characters"
}

Vérification de la disponibilité de l'e-mail ou du nom d'utilisateur

GET

/availability/username/{username}
Description Vérifie si le nom d'utilisateur spécifié est déjà utilisé par un autre compte et si le format est valide. Utile au moment de l'inscription.
Conditions Aucune.
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "Username availability and validity checked successfully",
  "content":
  {
    "is_available": true/false,
    "is_valid": true/false
  },
}
Echec N/A
GET

/availability/email/{email}
Description Vérifie si l'adresse e-mail spécifiée est déjà utilisée par un autre compte et si le format est valide. Utile au moment de l'inscription.
Conditions Aucune.
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "E-mail availability and validity checked successfully",
  "content":
  {
    "is_available": true/false,
    "is_valid": true/false
  },
}
Echec N/A

Activation du compte

POST

/account/activate/verify/{verification_code}
Description Déclenche la vérification du compte pour confirmer l'adresse e-mail.
Conditions Le compte doit ne pas avoir été vérifié.
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "Account successfully verified"
}
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid verification code"
}

Renvoi de l'e-mail de confirmation

POST 🔐

/account/activate/resend
Description Permet le renvoi de l'e-mail de confirmation afin d'activer le compte.
Conditions
  • Token existant et valide
  • Compte pas encore activé
  • Dernier e-mail envoyé il y a plus de 2 minutes
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "e-mail sent successfully"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Account already active"
}
{
  "success": false,
  "status": 429,
  "error": "TOO MANY REQUESTS",
  "message": "E-mail sent less than 2 minutes ago"
}

Mot de passe oublié

POST

/forgot
Description Permet d'envoyer un e-mail de récupération du mot de passe
Conditions
  • E-mail ou nom d'utilisateur valide
  • Dernier e-mail de récupération envoyé il y a plus de 2 minutes

(Pour plus de sécurité, le serveur renvoie 200 SUCCESS dans tous les cas)
Paramètres 
{
  "id": "<username> or <e-mail>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "If the username or e-mail address exists, an e-mail with instruction to recover your account has been sent to you."
}
Echec N/A

Récupération du compte

POST

/recover
Description Permet de changer son mot de passe en cas d'oubli via un code temporaire précédemment envoyé par e-mail
Conditions
  • Code de récupération existant et valide (expiration après 15 minutes)
  • Nouveau mot de passe fort
  • Nouveau mot de passe différent du précédent
Paramètres 
{
  "token": "<temporary recovery token>",
  "password": "<new password>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "password successfully reset"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": " 
    * New password contains forbidden characters /
    * New password is too weak /
    * New password must be different than current one "
}

Gestion du compte

Récupération des informations de l'utilisateur

GET 🔐

/account/get
Description Permet de récupérer le nom d'utilisateur et l'e-mail d'un utilisateur
Conditions Token existant et valide.
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "username": "<username>",
    "email": "<email>",
    "is_verified": true/false
  },
}
Echec N/A

Mise à jour de l'adresse e-mail

POST 🔐

/account/update/email
Description Permet de modifier l'adresse e-mail de l'utilisateur.
Conditions
  • Nouvel e-mail pas encore utilisé
  • Token existant et valide
Paramètres 
{
  "email": "<new e-mail>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "e-mail successfully updated"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": " 
    * E-mail format is invalid / 
    * E-mail is already taken "
}

Mise à jour du nom d'utilisateur

POST 🔐

/account/update/username
Description Permet de modifier le nom d'utilisateur.
Conditions
  • Nouveau nom d'utilisateur pas encore utilisé
  • Token existant et valide
  • Adresse e-mail vérifiée
Paramètres 
{
  "username": "<new username>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "username successfully updated"
}
Echec 
{
  "success": false,
  "status": 400,
  "error": "BAD REQUEST",
  "message": " 
    * Username contains forbidden characters / 
    * Username is already taken "
}
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Account must be verified to change username"
}

Mise à jour du mot de passe

POST 🔐

/account/update/password
Description Permet de mettre à jour le mot de passe de l'utilisateur.
Conditions
  • Nouveau mot de passe fort
  • Nouveau mot de passe différent du précédent
  • Token existant et valide
  • Adresse e-mail vérifiée
Paramètres 
{
  "password": "<new password>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "password successfully updated"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": " 
    * New password contains forbidden characters /
    * New password is too weak /
    * New password must be different than current one 
    * Account must be verified to change password "
}

Supprimer le compte

La suppression du compte nécessite une confirmation par e-mail.

Demande de suppression

POST 🔐

/account/delete/initiate
Description Permet d'initier la suppression du compte. Un e-mail avec un lien est alors envoyé par e-mail pour valider l'opération.
Conditions
  • Token existant et valide
  • Compte vérifié
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "An e-mail with a link has been sent to your e-mail address. Click the link to validate the deletion of your account"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Account must be verified."
}

Validation de la suppression

POST 🔐

/account/delete/validate
Description

Permet de valider la suppression du compte à l'aide du code de confirmation reçu par e-mail.

La suppression est définitive. Toutes les entités de carte possédées sont perdues et il n'est pas possible de les récupérer. Les codes de partages ne seront plus valides après la suppression. Toutes les cartes partagées sont conservées si le transfert a effectivement eu lieu avant la suppression.
Conditions
  • Token existant et valide
  • Code de confirmation envoyé il y a moins de 15 minutes
Paramètres 
{
    "token": "<validation token>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "The account has been permanently deleted"
}
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid confirmation code."
}
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Expired confirmation code"
}

Collection de cartes

Liste des cartes existantes dans le jeu

GET

/list/all
Description Permet de récupérer la liste de toutes les cartes existantes dans le jeu
Conditions Aucune.
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "cards": 
    [
      {
        "id": "<card_id>",
        "name": "<figure_name>",
        "description": "<card_description>",
        "code": "<card_code>",
        "birth": "<birth_year>",
        "death": "<death_year>",
        "img": "<image_path>",
        "category":
        {
          "id": "<category_id>",
          "name": "<category_name>"
        },
        "country":
        {
          "id": "<country_id>",
          "name": "<country_name>"
        }, 
        "continent":
        {
          "id": "<continent_id>",
          "name": "<continent_name>"
        }
      },
      {
        ...
      }
    ]
  }
}
Echec N/A

Liste des cartes possédées

GET 🔐

/collection
Description Permet de récupérer la liste de toutes les cartes
Conditions Token existant et valide
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "cards": 
    [
      {
        "id": "<card_id>",
        "quantity": {card_quantity},
        "is_gold": true/false,
        "name": "<figure_name>",
        "description": "<card_description>",
        "code": "<card_code>",
        "birth": "<birth_year>",
        "death": "<death_year>",
        "img": "<image_path>",
        "category":
        {
          "id": "<category_id>",
          "name": "<category_name>"
        },
        "country":
        {
          "id": "<country_id>",
          "name": "<country_name>"
        }, 
        "continent":
        {
          "id": "<continent_id>",
          "name": "<continent_name>"
        }
      },
      {
        ...
      }
    ],
    "entities":
    {
      "<card_id_1>":
      [
        {
          "entity_id": "<card_entity_id>",
          "is_shared": true/false,
          "share_code": "<share_code> or null",
          "is_gold": true/false  
        },
        {
          ...
        }
      ],
      "<card_id_2>":
      [
        ...
      ],
      ...
    }
  }
}
Echec N/A

Liste des entités possédées d'une carte en particulier

GET 🔐

/entities/{card_id}
Description Permet de récupérer la liste des entités de cartes possédées par l'utilisateur.
Conditions
  • Token existant et valide
  • Identifiant de carte valide
  • Carte possédée par l'utilisateur (min. 1 exemplaire)
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "entities":
    [
      {
        "entity_id": "<card_entity_id>",
        "is_shared": true/false,
        "share_code": "<share_code> or null",
        "is_gold": true/false  
      },
      {
        ...
      }
    ]
  }
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Card is not owned by user"
}
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid card ID"
}

Liste des catégories

GET 🔐

/categories
Description Récupère la liste de toutes les catégories de cartes existantes.
Conditions Token existant et valide
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "categories":
    [
      {
        "id": "<category_id>",
        "name": "<category_name>",
        "owned_qty": "<qty of cards owned of this category>",
        "total_qty": "<qty of cards in total in this category>",
        "completion_percent": "<percentage of completion of this category>"
      },
      ...
    ]
  }
}
Echec N/A

Liste des pays

GET 🔐

/countries

Description

Récupère la liste de tous les pays de cartes existantes.

Conditions

Token existant et valide

Paramètres

 Aucun.

Réussite

 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "countries":
    [
      {
        "id": "<country_id>",
        "name": "<country_name>",
        "owned_qty": "<qty of cards owned of this country>",
        "total_qty": "<qty of cards in total in this country>",
        "completion_percent": "<percentage of completion of this country>"
        "continent":
        {
          "id": "<continent_id>",
          "name": "<continent_name>"
        },
      },
      ...
    ]
  }
}

Echec

N/A

Liste des continents

GET 🔐

/continents

Description

Récupère la liste de tousles continents de cartes existantes.

Conditions

Token existant et valide

Paramètres

 Aucun.

Réussite

 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "continents":
    [
      {
        "id": "<continent_id>",
        "name": "<continent_name>",
        "owned_qty": "<qty of cards owned of this continent>",
        "total_qty": "<qty of cards in total in this continent>",
        "completion_percent": "<percentage of completion of this continent>"
      },
      ...
    ]
  }
}

Echec

N/A

Liste des cartes possédées dans une catégorie en particulier

GET 🔐

/collection/filter/category/{category_id}
Description Permet d'obtenir la liste des cartes possédées dans une catégorie en particulier
Conditions Token existant et valide
Paramètres Aucun.
Réussite

voir /collection
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid category ID"
}

Liste des cartes possédées dans un pays en particulier

GET 🔐

/collection/filter/country/{country_id}
Description Permet d'obtenir la liste des cartes possédées dans un pays en particulier
Conditions Token existant et valide
Paramètres Aucun.
Réussite

voir /collection
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid country ID"
}

Liste des cartes possédées dans un continent en particulier

GET 🔐

/collection/filter/continent/{continent_id}
Description Permet d'obtenir la liste des cartes possédées dans un continent en particulier
Conditions Token existant et valide
Paramètres Aucun.
Réussite

voir /collection
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid continent ID"
}

Pack de récompense

Vérification du statut du pack

GET 🔐

/reward/status
Description Permet de vérifier le statut du pack de récompense.
Conditions
  • Token existant et valide
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "is_available": true/false,
    "next_opening": "<next opening timestamp>"
  }
}
Echec N/A

Ouverture du pack

POST 🔐

/reward/open
Description Permet d'ouvrir le pack de récompenses
Conditions
  • Token existant et valide
  • Compte activé
  • Pack disponible à l'ouverture
Paramètres Aucun
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "cards": 
    [
      {
        "id": "<card_id>",
        "name": "<figure_name>",
        "description": "<card_description>",
        "code": "<card_code>",
        "birth": "<birth_year>",
        "death": "<death_year>",
        "img": "<image_path>",
        "is_new": true/false,
        "is_gold": true/false,
        "category":
        {
          "id": "<category_id>",
          "name": "<category_name>"
        },
        "country":
        {
          "id": "<country_id>",
          "name": "<country_name>"
        }
      },
      {
        ...
      }
    ]
  }
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "
    * Pack is not available yet
    * Account has not been activated yet. Please confirm your e-mail address. "
}

Partage des cartes

Récupération du statut de partage d'une carte

GET 🔐

/card/share/status/{card_id}
Description Récupère le statut de partage d'une carte
Conditions
  • Token existant et valide
  • Identifiant de carte valide
  • Carte possédée
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "success",
  "content":
  {
    "is_more_shareable": true/false,
    "is_more_shareable_gold": true/false,
    "entities":
    [
      {
        "id": "<card entity id>",
        "is_shared": true/false,
        "code": "<share_code> or null"
      },
      {
        ...
      }
    ]
  }
}
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid card ID"
}
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "You do not possess this card"
}

L'attribut is_more_shareable décrit si au moins une carte peut encore activer le partage, en plus de ceux qui sont déjà en cours de partage. En l'occurrence, l'attribut est à true si au moins deux entités n'ont pas le partage activé.

Activation du partage d'une carte

POST 🔐

card/share/enable/{entity_id}
Description Active le partage d'une entité d'une carte
Conditions
  • Token existant et valide
  • Compte activé
  • Identifiant d'entité valide
  • Entité possédée
  • Carte encore partageable
  • Entité pas encore partagée
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "card share enabled",
  "content":
  {
    "code": "<card share code>"
  }
}
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid entity ID"
}
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "
    * Card is not shareable
    * Card is already shared 
    * Account has not been activated yet. Please confirm your e-mail address "
}

Désactivation du partage d'une carte

POST 🔐

card/share/disable/{entity_id}
Description Active le partage d'une entité d'une carte
Conditions
  • Token existant et valide
  • Compte activé
  • Identifiant d'entité valide
  • Entité possédée
  • Partage activé
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "card share disabled"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "
    * Card is not shared
    * Account has not been activated yet. Please confirm your e-mail address" 
}
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid entity ID"
}

Utilisation d'un code de partage

POST 🔐

/card/activate/{share_code}
Description Permet l'utilisation d'un code de partage pour initier le transfert d'une carte
Conditions
  • Token existant et valide
  • Compte activé
  • Code de partage valide
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "card activated successfully",
  "content":
  {
    "id": "<card_id>",
    "quantity": {card_quantity},
    "is_gold": true/false,
    "name": "<figure_name>",
    "description": "<card_description>",
    "code": "<card_code>",
    "birth": "<birth_year>",
    "death": "<death_year>",
    "img": "<image_path>",
    "category":
    {
      "id": "<category_id>",
      "name": "<category_name>"
    },
    "country":
    {
      "id": "<country_id>",
      "name": "<country_name>"
    }, 
    "continent":
    {
      "id": "<continent_id>",
      "name": "<continent_name>"
    }
  }
}
Echec 
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid share code"
}
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "Account has not been activated yet. Please confirm your e-mail address"
}

Administration

Ces fonctions permettent d'effectuer l'administration de l'application et est uniquement destinée aux administrateurs (`user.is_admin = true`).

Créer une carte

POST 🔐

/admin/cards/create
Description Permet de créer une nouvelle carte.
Conditions
  • Token existant et valide
  • Posséder le rôle admin
Paramètres 
{
  "name": "<card name>",
  "description": "<card_description>",
  "rarity": "<card_rarity>(float)",
  "code": "<card_code>(int)",
  "birth": "",
  "death": "",
  "img": "<img_path>",
  "country": "<country name>",
  "continent": "<continent_name>",
  "category": "<category_name>"
}
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "card created successfully",
  "content":
  {
    "id": "<new card id>"
  }
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "
    * Card with the same name already exists" 
}

Supprimer une carte

POST 🔐

/admin/cards/delete/{card_id}
Description Permet de définitivement supprimer une carte.
Conditions
  • Token existant et valide
  • Posséder le rôle admin
  • Aucune entité de carte fait référence à cette carte
Paramètres Aucun.
Réussite 
{
  "success": true,
  "status": 200,
  "error": null,
  "message": "card deleted successfully"
}
Echec 
{
  "success": false,
  "status": 403,
  "error": "FORBIDDEN",
  "message": "There is still cards entities that reference this card" 
}
{
  "success": false,
  "status": 404,
  "error": "NOT FOUND",
  "message": "Invalid card ID" 
}

Classement des joueurs

TODO

Clone this wiki locally