Skip to content

API

Jump to bottom
Geoffrey Frogeye edited this page May 5, 2016 · 34 revisions

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
  • 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

##Utilisateur

###POST api/utilisateur/connexion Paramètres : (login AND mdp) XOR idCarte

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

Status : identifiants_invalides, carte_inconnue

###POST api/utilisateur/deconnexion Paramètres : aucun

Retour : aucun

Status : aucun

###POST api/utilisateur/mdp Droits nécessaires : ≥ 3 (si autre utilisateur)

Paramètres : login AND mdp

Retour : utilisateur_inconnu

###POST api/utilisateur/carte Droits nécessaires : ≥ 3 (si autre utilisateur)

Paramètres : login AND idCarte

Retour : utilisateur_inconnu

Status : aucun

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

Paramètres : aucun

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

Status : aucun

###POST api/utilisateur/fiche Droits nécessaires : ≥ 3 (si autre utilisateur)

Paramètres : login

Retour : login, droit, idCarte, transactions

Retour : utilisateur_inconnu

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

Paramètres : login AND mdp MAYBE idCarte AND droit

Retour : aucun

Status : utilisateur_existant

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

Paramètres : login AND droit

Retour : aucun

Status : utilisateur_inconnu

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

Paramètres : login

Retour : aucun

Status : utilisateur_inconnu

##Client

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

Paramètres : idCarte AND solde MAYBE decouvert

Retour : idTransaction, sldeNouveau

Status : solde_negatif (solde ≤ 0 AND decouvert faux), droits_insuffisants (decouvert vrai et droits < 3), client_existant

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

Paramètres : idCarte AND montant

Retour : idTransaction, soldeAncien, soldeNouveau

Status : client_inconnu, rechargement_negatif

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

Paramètres : idCarte AND (montant XOR quantite))

Retour : idTransaction, soldeAncien, soldeNouveau, montant

Status : solde_insuffisant (solde < 0 AND decouvert faux, retour sup: solde, manque), client_inconnu, paiement_negatif

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

Paramètres : idCarte

Retour : soldeAncien, idTransaction

Status : client_inconnu, solde_negatif

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

Paramètres : aucun

Retour : clients : liste des (idCarte, solde, MAYBE decouvert (si droits ≥ 3))

Status : aucun

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

Paramètres : idCarte

Retour : idCarte, decouvert (si droits ≥ 3), solde, transactions

Status : client_inconnu

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

Paramètres : idCarte AND decouvert

Retour : aucun

Status : client_inconnu

##Divers

###GET api/coucou Paramètres : aucun

Retour : aucun

Status : aucun

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

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

Paramètres : idCarte

Retour : client, utilisateur

Status : aucun

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

Paramètres : idTransaction

Retour : client, soldeAncien, soldeNouveau

Status : transaction_inconnue, transactions_deja_annulee, transaction_expiree (si droit < 3), transaction_autre (si login ≠ login qui a fait la transaction et droit < 3)

Notes : L'annulation de la création d'un client enlève seulement le solde initial

###POST api/refaire Droits nécessaires : ≥ 2

Paramètres : idTransaction

Retour : client, soldeAncien, soldeNouveau

Status : transaction_inconnue, transactions_deja_active, transaction_expiree (si droit < 3), transaction_autre (si login ≠ login qui a fait la transaction et droit < 3)

###POST api/transactions Droits nécessaires : ≥ 3

Paramètres : aucun

Retour : transactions

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&idCarte=AHS0DIEX"

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&idCarte=AHS0DIEX).

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",
        "idCarte": "AHS0DIEX",
        "solde": 48.3,
        "decouvert": 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

Clone this wiki locally