Skip to main content

Pour Commencer avec l'API Horsplace Proxy

Bienvenue dans la documentation de l'API Proxy Horsplace ! Cette API sert d'intermédiaire et de surcouche à l'API Horsplace principale, offrant un ensemble de points d'accès pour interagir avec le système d'étiquettes électroniques Horsplace.

Objectif de l'API​

L'objectif principal de cette API proxy est de fournir une interface contrôlée et sécurisée pour les applications tierces souhaitant intégrer les fonctionnalités de Horsplace. Elle permet de gérer :

  • Les modèles (templates) d'affichage pour les étiquettes.
  • Les données affichées sur les étiquettes.
  • Les stations de base.
  • Les étiquettes électroniques elles-mêmes.
  • Le matériel graphique (images de fond, logos).
  • Le contrôle des LEDs des étiquettes.

Schéma d’architecture​

Voici un aperçu global du fonctionnement du système Horsplace, avec les flux entre écrans, base station, API proxy et API principale :

Architecture système Horsplace

Qui peut utiliser cette API ?

L’API proxy Horsplace est réservée aux partenaires, éditeurs tiers ou structures clientes disposant d’une clé d’API valide. Elle permet une intégration fluide sans exposer directement l’API centrale, garantissant un meilleur contrôle des accès et de la sécurité.

Authentification​

L'accès à cette API proxy est contrôlé par une clé d'API unique (X-API-KEY) qui doit être fournie dans l'en-tête de chaque requête.

Authentification Admin

Pour interagir avec l'API Horsplace distante (via ce proxy), votre application cliente doit d'abord s'authentifier auprès du proxy pour obtenir un token JWT. Ce token sera ensuite utilisé par le proxy pour s'authentifier auprès de l'API Horsplace principale.

Flux d'authentification initial :

  1. Votre application cliente (configurée dans ce proxy avec des identifiants pour l'API Horsplace distante) fait une requête POST sur le point d'API {{baseUrl}}/api/horstable/login en fournissant sa X-API-KEY (celle de votre application cliente enregistrée dans ce proxy).
  2. Si la X-API-KEY est valide, le proxy contacte l'API Horsplace distante avec les identifiants préconfigurés pour votre application cliente et obtient un token JWT de l'API Horsplace.
  3. Le proxy retourne ce token JWT de l'API Horsplace à votre application cliente.
  4. Important : Les contrôleurs de ce proxy utiliseront ensuite ce token JWT (obtenu à l'étape 2 et stocké côté serveur par le proxy) pour toutes les requêtes ultérieures vers l'API Horsplace distante. Votre application cliente n'a pas besoin de gérer directement ce token JWT de l'API Horsplace après l'avoir reçu, mais doit continuer à utiliser sa propre X-API-KEY pour s'authentifier auprès de ce proxy.

Consultez la section Connexion API Horsplace pour les détails de cette première étape.

Structure des Requêtes et Réponses​

  • Format : Toutes les données sont échangées au format JSON.
  • Méthodes HTTP : L'API utilise les verbes HTTP standard (GET, POST, PUT, DELETE).
  • URL de base : L'URL de base pour tous les appels est {{baseUrl}}.

Gestion des Erreurs​

L'API utilise les codes de statut HTTP standard pour indiquer le succès ou l'échec des requêtes :

  • 200 OK / 201 Created / 204 No Content : Succès.
  • 400 Bad Request : La requête est malformée (par exemple, JSON invalide, paramètres manquants).
  • 401 Unauthorized : Authentification requise ou échec de l'authentification (clé d'API manquante ou invalide pour le proxy).
  • 403 Forbidden : Accès refusé (par exemple, permissions insuffisantes pour l'action demandée).
  • 404 Not Found : La ressource demandée n'existe pas.
  • 422 Unprocessable Entity : Les données fournies sont sémantiquement incorrectes (par exemple, violation de règles métier).
  • 500 Internal Server Error : Erreur interne du serveur proxy.
  • 502 Bad Gateway / 503 Service Unavailable : Problème de communication avec l'API Horsplace distante.

Les réponses d'erreur contiendront généralement un corps JSON avec plus de détails.