API et identifiants

Séparer les droits#

Licences serveur, droits utilisateur et jetons de téléversement sont distincts. Ces jetons expirent et ne permettent que le dépôt de preuves, jamais la gestion du panel.

Gérer les erreurs#

Évitez les boucles rapides face aux erreurs ou limites. Ne répétez pas automatiquement une écriture financière incertaine. Ne publiez pas les en-têtes d’authentification dans URL, client ou journaux.

Associer endpoint et permission#

Aucune clé universelle. La licence authentifie le pont SaaS ; les tokens de composants peuvent exiger des scopes. Les actions navigateur nécessitent rôle, droits et CSRF selon l’action. Les tokens de preuves restent limités au contexte, serveur et requête, sans administration.

L’exemple montre les en-têtes seulement. Le marqueur n’est pas valide ; la ressource produit le protocole. Un JSON arbitraire ne devient pas une tâche. Gardez l’autorisation entre serveurs, hors navigateur, URL, analytics et traces partagées.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

• Gestion de licence

Séparer réponse HTTP et tâche#

Le pont accepte POST JSON, pas du SQL ou des tables libres. pending ou claimed reste en cours. Vérifiez le résultat final avant d’annoncer le succès.

• 401 : vérifier licence du bon serveur, non régénérée.
• 403 bridge_disabled / subscription_inactive / permission_denied : vérifier la carte Tosun Connect du serveur (bridge_disabled signifie que la connexion y a été coupée), abonnement et droits ; répéter ne donne pas accès.
• 405 / 415 : corriger méthode et JSON Content-Type ; ne pas répéter un JSON invalide.
• 429 : respecter Retry-After et temporiser ; le pont limite concurrence et augmente le délai sur erreur.
• 503 / timeout : noter heure et référence expurgées, examiner connexion.

• Pont et erreurs

Tester une petite opération#

Utilisez un serveur test ou personnage contrôlé. Lisez une fois, vérifiez le personnage et comparez au jeu. Opérations fixes et pagination ne constituent pas un dump complet. Gardez une référence distinguant tâche et répétition.

Journalisez seulement statut, durée et référence non secrète. Retirez tokens et données personnelles des rapports publics. Retestez après modification de clés, droits ou paquet.

Ne distribuez pas le même token administratif partout. Limitez les scopes et révoquez les accès inutilisés. Après changement d’endpoint ou droits, testez succès et refus, sans vous fier à un ancien résultat.

1. Vérifier succès sur votre serveur et refus de clés erronées/révoquées.
2. Le personnel sans droit doit être refusé ; aucun test sur d’autres clients.
3. Afficher distinctement pending, failed, expired et done, sans succès générique.
4. Avec unknown_outcome financier, vérifier solde réel et traces avant réécriture.

• Requêtes limitées
• Frameworks

Séparer navigateur et protocole serveur#

/api/tenant_db_bridge.php authentifie le personnel par session. POST, application/json, _csrf valide et compte du tenant courant sont requis ; le corps est limité à 4096 octets. action vaut enqueue ou result. Une licence ne crée pas une session. Pouvoir lire ne permet pas d’écrire des soldes ; l’opération est autorisée séparément.

/api/server_db_bridge.php échange santé, travaux et résultats depuis le serveur de jeu. Il utilise POST JSON et une licence Bearer, avec une limite de 65536 octets. Cookie et CSRF ne remplacent pas ce protocole. Identifiez la route avant de changer des identifiants ; ceux d’une autre route ne corrigent pas l’accès. N’imitez pas le protocole intégré avec un JSON arbitraire.

Distinguer acceptation et achèvement#

ok=true peut confirmer une requête HTTP acceptée sans prouver le travail en jeu terminé. Suivez id, operation et status dans request. pending attend ; claimed est pris par le serveur. done est terminé, failed a échoué et expired a expiré. Conservez le contexte server_id et request_id pour lire le résultat.

Vérifiez statut final et error avant d’annoncer un succès. Une demande identique en attente peut retourner le travail existant ; cela ne garantit pas une répétition illimitée permanente. Arrêtez les écritures d’argent à unknown_outcome. Timeout ou résultat invalide ne prouve pas absence d’effet. Comparez solde actuel, cible précédente et audit ; ne supprimez pas les preuves pour recommencer.

Rédiger un rapport développeur concis#

Pour 405 vérifiez méthode ; pour 415, JSON Content-Type ; pour 400, JSON valide et champs admis. Côté navigateur, 401 concerne la session et 419 la vérification CSRF ; rouvrez par navigation normale. Pour 404 vérifiez le contexte sans tester un autre client. Attendez les travaux actifs sur 429.

Pour 503 ou réseau incertain, notez heure, endpoint, statut HTTP, opération et référence non secrète. L’exemple est une note de support, pas un corps de requête. Excluez cookies, Authorization, _csrf, licences et données joueurs. Corrigez l’étape responsable au lieu de répéter rapidement ; validez d’abord une lecture contrôlée.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

Lire une page de joueurs avec deux corps JSON vérifiés#

Cet exemple lit la première page des joueurs dans un navigateur déjà connecté au panneau de votre compte. Le serveur 123 et l’identifiant sont fictifs : utilisez votre serveur et request.id renvoyé par enqueue. Remplacez CURRENT_PAGE_CSRF par la valeur valide de la page actuelle. Ce n’est pas une licence serveur et elle ne doit pas figurer dans un message au support. Il faut un POST de même origine, application/json et la session du navigateur. La lecture exige servers.manage ou players.view ; enqueue est refusé dans la démo en lecture seule.

Le premier corps envoie seulement un cursor vide ; cette opération renvoie au maximum 25 enregistrements par page. N’ajoutez ni limit, ni SQL, nom de table, chaîne de connexion ou paramètres monétaires. Si la première réponse indique pending, interrogez ce travail avec le second corps au lieu d’en créer un autre. Pour done, lisez request.result.items. Si request.result.has_more vaut true, utilisez request.result.next_cursor lors de la prochaine demande volontaire de page. Interprétez une liste vide avec son statut de fin réussie. Ces modèles ne contiennent aucun identifiant secret utilisable. Limitez le premier essai à une lecture sur votre serveur de test ; ils ne servent pas à donner des droits administrateur à une extension publique.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

• Passerelle MySQL
• Accès au panneau et au compte

Distinguer le délai HTTP de l’expiration du travail#

Supposons qu’enqueue soit accepté à 14:03:10 et que request.id soit enregistré, mais qu’un appel result perde ensuite sa connexion. Une requête HTTP du panneau peut s’arrêter après douze secondes ; le travail en file expire 120 secondes après sa création. L’abandon de la requête par le navigateur n’annule pas ce travail serveur. Ne présentez donc pas « aucune réponse » comme un résultat expired ou failed. Conservez l’identifiant connu et lisez result avec le même server_id quand la connexion revient. Le panneau vérifie normalement les résultats en attente toutes les trois secondes ; n’ajoutez pas une boucle de requêtes incessantes.

Si la lecture players.list finit en expired avec request_expired, notez l’erreur, rétablissez la connexion puis lancez une nouvelle lecture volontaire. Pour player.money.set, une expiration après claimed ou un résultat invalide peuvent produire unknown_outcome : cela ne prouve pas que le solde n’a pas changé. Arrêtez les écritures et examinez le solde actuel ainsi que l’opération existante. Les résultats ne constituent pas une archive illimitée ; les enregistrements expirés sont supprimés plus tard par un nettoyage borné. Si le travail n’est plus trouvé, ne devinez pas son résultat en envoyant une nouvelle modification d’argent. Pour le support, gardez seulement référence non secrète, heure, operation et dernier statut connu.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile

• Passerelle MySQL
• Performances et intervalles d’attente