API

Moyen de communiquer entre les applications clientes (android et web) et le serveur.

La couche de communication utilisée sera de l'HTTPS (plus simple). Si des paramètres sont nécessaires lors des appels à l'API, la requête utilisée sera de type POST, sinon GET. Les données renvoyées par le serveur seront de type JSON (plus simple). Pour le temps de l'alpha, on fera des requêtes non-securisées (HTTP).

#Comportement généraux

• chaque réponse contiendra une clef status qui contiendra ok si la requête a abouti, un code d'erreur sinon (voir différents codes d'erreur)
• Les status pour chaque requête possible dans la présente documentation donnent les status qui peuvent être renvoyé par le serveur (ok est sous-entendu) lors du fonctionnement normal de l'application. Il peut cependant renvoyer un autre status ou alors un code HTTP autre que 200. Dans ce cas, l'application doit afficher un message d'erreur (idéalement avec le status) mais ne pas crasher lamentablement 😃
• chaque requête peut être erroné, dans ce cas le status sera requete_malforme (je vous jure c'est super utile pour débugger) et ne pas crasher lamentablement non plus
• chaque requête (excepté coucou et connexion) devront contenir un jeton de connexion. S'il est invalide, le status sera jeton_invalide
• chaque requête contenant en paramètre un couple loginLille1 et idCarte retournera un status carte_differente si le couple n'est pas le même dans la Base De Données. À l'exception de api/connexion, elles prendront aussi un paramètre majIdCarte qui, si il est présent et vrai, mettra à jour dans la base de données la valeur idCarte pour le loginLille1 donné. on verra ça plus tard
• Le serveur peut retourner erreur_bdd ou erreur_generique si une erreur innatendue arrive

#Types d'utilisateur

• 0 : honeypot (aucun droit) (par défaut)
• 1 : BDE (créer des comptes uniquement)
• 2 : membre bar (tout sauf modifier les comptes bar et changer la valeur "découvert autorisé")
• 3 : prez bar (absolument tout)

#Requêtes possibles

##GET api/coucou Droits nécessaires : ≥ 0

Paramètres : aucun

Retour : aucun

Status : aucun

Note : Utilisé pour vérifier si le serveur est bien là.

##POST api/utilisateur/connexion Droits nécessaires : ≥ 0

Paramètres : (login AND mdp) XOR idCarte

Retour : jeton (une valeur aléatoire), login, droit

Status : identifiants_invalides, carte_inconnue, carte_differente

##POST api/client/ajouter Droits nécessaires : ≥ 1

Paramètres : idCarte AND solde MAYBE decouvert

Retour : idTransaction

Status : solde_insuffisant (solde < 0 AND decouvert faux), droits_insuffisants (decouvert vrai et droits < 3), carte_non_lille1, etudiant_deja_enregistre

##POST api/transaction/rechargement Droits nécessaires : ≥ 2

Paramètres : idCarte AND montant

Retour : idTransaction

Status : etudiant_inconnu

##POST api/utilisateur/deconnexion Droits nécessaires : ≥ 1

Paramètres : aucun

Retour : aucun

Status : aucun

##POST api/utilisateur/mdp Droits nécessaires : ≥ 1

Paramètres : login AND nvMdp

Retour : aucun

Status : droits_insuffisants (si login entré != login et droits < 3)

##POST api/client/carte Droits nécessaires : ≥ 1

Paramètres : loginLille1 AND nvIdCarteEtudiant

Retour : aucun

Status : usurpation_identite (loginLille1 lu sur la nouvelle carte != loginLille1 entré)

##POST api/utilisateur/droit Droits nécessaires : ≥ 3

Paramètres : login AND nvNiveauDroit

Retour : aucun

Status : aucun

##POST api/utilisateur/liste Droits nécessaires : ≥ 3

Paramètres : aucun

Retour : utilisateurs : liste des (login, droit, idCarte)

Status : aucun

##POST api/transaction/paiement Droits nécessaires : ≥ 2

Paramètres : idCarte AND montant MAYBE nbConso

Retour : idTransaction

Status : solde_insuffisant (solde < 0 AND decouvertAutorise faux), etudiant_inconnu

##POST api/transaction/vidange Droits nécessaires : ≥ 2

Paramètres : idCarte

Retour : montant, idTransaction

Status : etudiant_inconnu

##POST api/transaction/annuler Droits nécessaires : ≥ 2

Paramètres : idTransaction

Retour : aucun

Status : aucun

##POST api/client/liste Droits nécessaires : ≥ 2

Paramètres : aucun

Retour : clients : liste des (idCarte, solde, MAYBE decouvertAutorise (si droits >= 3))

Status : aucun

##POST api/client/fiche Droits nécessaires : ≥ 2

Paramètres : idCarte OR loginLille1

Retour : loginLille1, idCarte, decouvertAutorise, solde, transactions

Status : aucun

##POST api/client/decouvert Droits nécessaires : ≥ 3

Paramètres : idCarte AND nvDecouvertAutorise

Retour : aucun

Status : aucun

##POST api/utilisateur/ajouter Droits nécessaires : ≥ 3

Paramètres : login AND mdp MAYBE loginLille1 MAYBE idCarte AND droit

Retour : aucun

Status : carte_non_lille1

##POST api/utilisateur/carte Droits nécessaires : ≥ 3

Paramètres : login MAYBE loginLille1 AND idCarte

Retour : aucun

Status : carte_non_lille1

##POST api/utilisateur/supprimer Droits nécessaires : ≥ 3

Paramètres : login

Retour : aucun

Status : aucun

#Exemple Il est possible de tester l'API avec la commande curl, exemple :

curl 10p5.clubinfo.frogeye.fr/api/client/fiche --data "jeton=Phohhu3eengeingae8kab3weif3neb&loginLille1=petite.jaja"

Cette commande envoie les données au serveur comme le ferait le client Android ou Web. C'est la bibliothèque qui fait les appels HTTP de la plateforme, qui génère ces données, on aura uniquement besoin de lui donner l'IP du serveur (ici un nom de domaine), le lien vers l'appel API que l'on veut faire (ici api/client/fiche), et les données que l'on veut lui envoyer (ici jeton=Phohhu3eengeingae8kab3weif3neb&loginLille1=petite.jaja).

POST /api/client/fiche HTTP/1.1
Host: 10p5.clubinfo.frogeye.fr
User-Agent: curl/7.47.1
Accept: */*
Content-Length: 60
Content-Type: application/x-www-form-urlencoded

Le serveur obtiendra ces données, vérifiera si le jeton est ok, si les droits sont suffisant, si la requête est correcte, vérifiera si les données existent, modifera la base si nécessaire, créera un tableau associatif avec les éléments de réponse, le transformera en JSON, puis enfin le renverra au serveur. Ici on part du principe que Phohhu3eengeingae8kab3weif3neb est un jeton encore valide pour le président du bar. (le header (la première partie) est généré par le serveur web et PHP automatiquement)

HTTP/1.1 200 OK
Date: Mon, 11 Apr 2016 11:34:30 GMT
Server: Apache/2.4.18 (Unix) OpenSSL/1.0.2g PHP/7.0.5
Strict-Transport-Security: max-age=63072000; includeSubdomains; preload
X-Powered-By: PHP/7.0.5
Access-Control-Allow-Origin: *
Content-Length: 333
Content-Type: application/json

{
        "status": "ok",
        "loginLille1": "petite.jaja",
        "idCarte": "AHS0DIEX",
        "solde": 48.3,
        "decouvertAutorise": false,
        "transactions": [{
                "id": 5,
                "type": 1,
                "date": 1460369884183,
                "montant": 50,
                "qte": 0,
                "valide": true
        }, {
                "id": 6,
                "type": 3,
                "date": 1460370161326,
                "montant": 1.7,
                "qte": 1,
                "valide": true
        }]
}

Reste au client de faire quelque choses avec la deuxième partie