Applicable à : Fournisseurs d’intégration
Application(s) : Logiciel API externe
Cet article couvrira les points suivants :
- Comprendre les bases des API
- Différences entre les API publiques et privées de PlayHQ
- Configuration et accès aux API publiques PlayHQ
- Dépannage des problèmes courants d’API
Articles connexes :
Ressources :
- Documentation API PlayHQ : docs.playhq.com/tech
Comprendre les bases des API
Si vous êtes un utilisateur avancé des API, vous pouvez probablement passer cette section, mais si vous êtes tombé sur cette page par curiosité sur ce qu’est une API, ce qui suit pourrait vous donner un peu de contexte.
Une API est un intermédiaire logiciel qui permet à deux applications de communiquer entre elles.
Avec les API de PlayHQ, vous pouvez :
- Afficher les rencontres et résultats sur votre site web
- Collecter des statistiques de jeu pour publier les résultats du week-end
- Intégrer les données PlayHQ avec d’autres systèmes
Quelle est la différence entre les API publiques et privées de PlayHQ ?
La principale différence entre les API privées et publiques est la sélection des données retournées dans la réponse.
Les API publiques respecteront les paramètres de visibilité sur PlayHQ en ne renvoyant que les données liées qui sont définies comme VISIBLES dans le portail d’administration PlayHQ.
Par exemple, si un administrateur définit une organisation comme CACHÉE dans le portail d’administration PlayHQ, nous ne renverrons pas cette organisation ni aucune information subsidiaire (compétitions, rencontres associées) via les API.
Cas d’utilisation :
- Widgets de site web affichant les rencontres, résultats et classements
- Applications accessibles au public sur Internet
Limitations des données :
- Les organisations, équipes ou participants cachés n’apparaîtront pas dans les résultats
- Respecte tous les paramètres de confidentialité configurés dans PlayHQ
Les API privées enverront des données, qu’elles soient définies comme VISIBLES ou CACHÉES dans le portail PlayHQ.
Par exemple, si un participant a défini son profil comme CACHÉ dans le portail des participants PlayHQ, nous transmettrons son nom, courriel, genre, etc. via les API.
Les API privées ne sont pas destinées à être utilisées par le grand public et seuls les partenaires PlayHQ approuvés y ont accès.
Cas d’utilisation :
- Partenaires officiels PlayHQ (par exemple, systèmes de gestion des arbitres, fournisseurs de diffusion en direct)
Exigences d’accès :
- Accord formel avec PlayHQ, incluant les directives d’utilisation des données
- Jetons d’authentification fournis par PlayHQ
Accès restreint
Les API privées sont celles qui nécessitent une autorisation requise (pour un Bearer {JWT_Auth_Token}). Ces API privées sont restreintes et uniquement accessibles aux partenaires PlayHQ approuvés.
Configuration des API publiques PlayHQ
Obtention des identifiants API
Si vous êtes impliqué dans un club ou une ligue, veuillez contacter votre association afin qu’elle puisse demander des identifiants en votre nom auprès de PlayHQ.
Si vous n’appartenez pas à un club mais souhaitez publier des données PlayHQ, veuillez soumettre une demande via votre sport concerné à https://www.playhq.com/au/contact
Utilisation de l’URL de base correcte
Si vous êtes situé en Australie ou en Nouvelle-Zélande (par exemple AFL, Cricket Australia, Basketball Victoria, New Zealand Cricket), utilisez l’URL de base : https://api.playhq.com comme point de départ pour effectuer une requête API.
Si vous êtes situé au Royaume-Uni ou en Europe (par exemple Basketball England), utilisez l’URL de base : https://api.euprod.playhq.com
Si vous êtes situé au Canada (p. ex. Rugby Canada), utilisez l'URL de base : https://api.caprod.playhq.com
Trouver les points de terminaison API
- Visitez la documentation API PlayHQ à docs.playhq.com/tech
- Naviguez vers le point de terminaison API pertinent dans la colonne de gauche, étiqueté "GET"
- Sélectionnez l’API spécifique dont vous avez besoin
- Copiez l’URL du serveur API (par exemple https://api.playhq.com/v1/organisations/:id/seasons)
- Développez les titres des réponses pour voir tous les champs et leurs réponses disponibles qui peuvent être retournées
Trouver les API publiques
Les API publiques sont librement accessibles et ne nécessitent aucun jeton d’autorisation. Si vous rencontrez une demande de jeton d’autorisation, vous avez tenté d’accéder à un point de terminaison d’API privée. Ces API privées sont restreintes et uniquement accessibles aux partenaires PlayHQ approuvés.
Faire une requête avec vos identifiants API
- Ouvrez votre logiciel externe de test d’API (par exemple, Postman)
- Créez une nouvelle requête GET
- Collez l’URL du serveur API PlayHQ (par exemple https://api.playhq.com/v1/organisations/:id/seasons)
- Ajoutez vos paramètres d’en-tête :
x-api-key : [également appelé Client ID - c’est un UUID]
x-phq-tenant : [également appelé le nom court du sport/locataire, en minuscules - par exemple bv, afl, ca] - Ajoutez vos paramètres de chemin :
le cas échéant - par exemple, id : [chaîne pertinente listée dans la documentation] - Envoyez la requête pour valider les données retournées
Questions fréquemment posées
PlayHQ offre une grande quantité de données relatives aux rencontres, résultats et classements des compétitions via les API publiques disponibles.
Pour une liste détaillée, consultez les points de terminaison étiquetés "GET" dans la documentation API PlayHQ.
Les API privées sont celles qui nécessitent une autorisation requise (pour un Bearer {JWT_Auth_Token}), et seuls les partenaires PlayHQ approuvés y ont accès.
Les ID d’organisation sont des identifiants uniques de 32 chiffres (UUID) qui ne sont pas facilement visibles sur le site web. Pour en obtenir un :
- Contactez l’administrateur de votre ligue ou club
- Une fois que vous avez l’ID d’organisation, vous pouvez l’utiliser pour appeler diverses API :
- Avec l’ID d’organisation, appelez "Saisons pour organisation" pour récupérer les ID de saison.
- Avec un ID de saison, appelez "Grades pour saison" pour récupérer les ID de grade.
- Avec un ID de grade, appelez “rencontre pour grade” pour récupérer les ID de jeu.
- Avec un ID de jeu, appelez “Résumé pour jeu (Public)” pour obtenir les résultats d’un jeu.
Il existe une URL de base différente selon la localisation dans PlayHQ Production.
Régions AUS & NZ : https://api.playhq.com
Régions UK & EU : https://api.euprod.playhq.com
Régions CA : https://api.caprod.playhq.com
Si vous avez obtenu l’accès à nos environnements UAT AUS & NZ, l’URL du serveur API PlayHQ en UAT est : https://api.uat.playhq.com
Les informations complètes sur les points de terminaison pour chaque API se trouvent dans la documentation API PlayHQ.
Si vous constatez des données incomplètes ou manquantes dans vos réponses API, vous êtes probablement confronté à la pagination. Pour les points de terminaison pouvant retourner de grands ensembles de données, l’API PlayHQ utilise une pagination basée sur un curseur (généralement 100 éléments) pour maintenir la performance. Pour récupérer l’ensemble complet des données, vous devrez effectuer plusieurs requêtes.
Lorsque metadata.hasMore est vrai dans votre réponse API, cela signifie qu’il y a plus de réponses disponibles pour votre requête, accessibles via un paramètre curseur. Cela vous permet de paginer à travers tous les résultats disponibles en continuant à faire des requêtes avec la dernière valeur du curseur jusqu’à recevoir une réponse où metadata.hasMore est faux.
Pour récupérer toutes les données disponibles :
- Faites votre requête API initiale au point de terminaison
- Vérifiez si
metadata.hasMoreesttruedans la réponse - Si oui, faites une autre requête au même point de terminaison, en ajoutant le paramètre curseur (c’est-à-dire ?cursor=) avec la valeur
metadata.nextCursoraprès = de la réponse précédente - Continuez ce processus, en collectant tous les résultats, jusqu’à recevoir une réponse où
metadata.hasMoreestfalse
Exemple :
// Première requête
GET https://api.playhq.com/v1/{endpoint}
// La réponse inclut metadata.hasMore : true et la valeur metadata.nextCursor
// Faites la requête suivante avec le curseur
GET https://api.playhq.com/v1/{endpoint}?cursor={cursor_value}
Vérifiez toujours les champs metadata dans vos réponses pour vous assurer que vous récupérez des ensembles de données complets.