Liste de contrôle V2 de l’API REST rest-api-v2-checklist

Conditions requises

Risques

Utilisez une application enregistrée avec la portée API REST v2 .

Risques déclenchant des réponses d’erreur HTTP 401 « Non autorisé », surchargeant les ressources système et augmentant la latence.

Stockez les informations d’identification du client dans un espace de stockage persistant et réutilisez-les pour chaque demande de jeton d’accès.

Risque de perte de l’authentification lors de la régénération des informations d’identification du client.

Stockez les jetons d’accès dans un espace de stockage persistant et réutilisez-les jusqu’à leur expiration.

Ne demandez pas de nouveau jeton pour chaque appel API REST v2. Actualisez les jetons d’accès uniquement lorsqu’ils expirent.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Conditions requises

Risques

Récupérez la réponse de configuration uniquement lorsque vous devez inviter l’utilisateur à sélectionner son MVPD (fournisseur de télévision) avant la phase d’authentification.

Il n’est pas nécessaire de récupérer la réponse de configuration lorsque :

• L’utilisateur est déjà authentifié.
• L’utilisateur se voit proposer un accès temporaire.
• L’authentification de l’utilisateur a expiré, mais celui-ci peut être invité à confirmer qu’il est toujours abonné au MVPD sélectionné précédemment.

Risque de surcharger les ressources système et d’augmenter la latence.

Stockez la sélection du fournisseur de télévision payante (MVPD) de l’utilisateur dans un espace de stockage persistant afin de l’utiliser lors de toutes les phases suivantes :

• Dans le magasin de réponse de configuration, l’utilisateur a sélectionné MVPD « id ».
• Dans le magasin de réponse de configuration, l’utilisateur a sélectionné MVPD « displayName ».
• Dans le magasin de réponse de configuration, l’utilisateur a sélectionné MVPD « logoUrl ».

Risque de surcharger les ressources système et d’augmenter la latence.

Conditions requises

Risques

Démarrez le mécanisme d’interrogation dans les conditions suivantes :

Authentification effectuée dans l’application principale (écran)

• L’application principale (de diffusion en continu) doit commencer à interroger l’utilisateur ou l’utilisatrice lorsqu’il ou elle atteint la page de destination finale, une fois que le composant de navigateur charge l’URL spécifiée pour le paramètre « redirectUrl » dans la requête de point d’entrée Sessions.

Authentification effectuée dans une application secondaire (écran)

• L’application principale (de diffusion en continu) doit commencer à interroger l’utilisateur dès qu’il lance le processus d’authentification, juste après avoir reçu la réponse du point d’entrée Sessions et affiché le code d’authentification à l’utilisateur.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Arrêtez le mécanisme d’interrogation sous les conditions suivantes :

Authentification réussie

• Les informations de profil de l’utilisateur ont été récupérées avec succès, confirmant leur statut d’authentification. L’interrogation n’est donc plus nécessaire.

Session d’authentification et expiration du code

• La session d’authentification et le code expirent, l’utilisateur ou l’utilisatrice doit redémarrer le processus d’authentification et l’interrogation à l’aide du code d’authentification précédent doit être arrêtée immédiatement.

Nouveau code d’authentification généré

• Si l’utilisateur demande un nouveau code d’authentification, la session existante est invalidée et l’interrogation avec le code d’authentification précédent doit être arrêtée immédiatement.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Configurez la fréquence du mécanisme d’interrogation dans les conditions suivantes :

Authentification effectuée dans l’application principale (écran)

• L’application principale (de diffusion en continu) doit effectuer une interrogation toutes les 3 à 5 secondes ou plus.

Authentification effectuée dans une application secondaire (écran)

• L’application principale (de diffusion en continu) doit effectuer une interrogation toutes les 3 à 5 secondes.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Stockez des parties des informations de profil de l’utilisateur dans un stockage persistant afin d’améliorer les performances et de minimiser les appels API REST v2 inutiles.

La mise en cache doit se concentrer sur les champs de réponse des profils suivants :

mvpd

• L’application cliente peut l’utiliser pour suivre le fournisseur de télévision sélectionné par l’utilisateur et continuer à l’utiliser pendant les phases de préautorisation ou d’autorisation.
• Lorsque le profil utilisateur actuel expire, l’application cliente peut utiliser la sélection MVPD mémorisée et demander à l’utilisateur de confirmer.

attributs

• Utilisé pour personnaliser l’expérience utilisateur en fonction de différentes clés de métadonnées d’utilisateur (par exemple, zip, maxRating, etc.).
• Les métadonnées de l’utilisateur sont disponibles une fois le flux d’authentification terminé. Par conséquent, l’application cliente n’a pas besoin d’interroger un point d’entrée distinct pour récupérer les informations de métadonnées de l’utilisateur, car elles sont déjà incluses dans les informations de profil.
• Certains attributs de métadonnées peuvent être mis à jour pendant la phase d’autorisation, selon le MVPD (par exemple, la charte) et l’attribut de métadonnées spécifique (par exemple, householdID). Par conséquent, l’application cliente peut avoir besoin d’interroger à nouveau les API Profiles après autorisation pour récupérer les dernières métadonnées de l’utilisateur.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Conditions requises

Risques

Utilisez les décisions de préautorisation pour le filtrage de contenu et jamais pour les décisions de lecture.

Risque de violer les accords contractuels entre Programmer, MVPD et Adobe.

Risques de contournement de nos systèmes de surveillance et d'alerte.

Gérez les codes d’erreur améliorés de manière appropriée et utilisez le champ d’action pour déterminer les étapes de correction nécessaires.

Seul un nombre limité de codes d’erreur améliorés justifie une nouvelle tentative, alors que la plupart nécessitent d’autres résolutions, comme spécifié dans le champ d’action.

Assurez-vous que tout mécanisme de reprise implémenté pour récupérer les décisions de préautorisation n’entraîne pas une boucle sans fin et limite les reprises à un nombre raisonnable (c’est-à-dire 2-3).

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Mettre en cache les décisions d’autorisation réussies en mémoire pour améliorer les performances et minimiser les appels API REST v2 inutiles, car les mises à jour d’abonnement pendant l’exécution de l’application sont peu fréquentes.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Conditions requises

Risques

Obtention des décisions d’autorisation avant la lecture, qu’une décision de préautorisation existe ou non.

Autorisez les flux à continuer sans interruption même si le jeton multimédia expire pendant la lecture et demandez une nouvelle décision d’autorisation contenant un jeton multimédia (frais) lorsque l’utilisateur effectue sa prochaine demande de lecture, que ce soit pour la même ressource ou pour une autre ressource.

Les diffusions en direct s’exécutant pendant des périodes prolongées peuvent choisir de demander une nouvelle décision d’autorisation à la suite d’opérations vidéo, telles que la suspension du contenu, le lancement d’interruptions commerciales ou la modification des configurations au niveau des ressources lorsque le MRSS est soumis à des modifications.

Risque de violer les accords contractuels entre Programmer, MVPD et Adobe.

Risques de contournement de nos systèmes de surveillance et d'alerte.

Gérez les codes d’erreur améliorés de manière appropriée et utilisez le champ d’action pour déterminer les étapes de correction nécessaires.

Seul un nombre limité de codes d’erreur améliorés justifie une nouvelle tentative, alors que la plupart nécessitent d’autres résolutions, comme spécifié dans le champ d’action.

Assurez-vous que tout mécanisme de reprise implémenté pour récupérer les décisions d’autorisation n’entraîne pas une boucle sans fin et limite les reprises à un nombre raisonnable (c’est-à-dire 2-3).

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Conditions requises

Risques

Implémentez l’API logout pour permettre aux utilisateurs de se déconnecter manuellement, d’arrêter leur profil authentifié et de suivre le nom d’action v2 de l’API REST spécifié pour chaque profil supprimé :

• Pour les fichiers MVPD prenant en charge un point d’entrée de déconnexion, l’application cliente doit accéder à l’« URL » fournie dans un user-agent.
• Pour les profils de type « appleSSO », l’application cliente nécessite de guider l’utilisateur pour également se déconnecter au niveau du partenaire (paramètres système d’Apple).

Risque de dysfonctionnement de l’application cliente en raison d’une prise en charge manquante côté application cliente.

Conditions requises

Risques

Envoyez l’en-tête Authorization pour chaque requête API REST v2.

Risques déclenchant des réponses d’erreur HTTP 401 « Non autorisé », surchargeant les ressources système et augmentant la latence.

Envoyez l’en-tête AP-Device-Identifier pour chaque requête API REST v2.

Même lorsque la requête provient d’un serveur pour le compte d’un appareil, la valeur de l’en-tête AP-Device-Identifier doit refléter l’identifiant réel de l’appareil de diffusion en continu.

Risque de déclencher des réponses d'erreur HTTP 400 « Bad Request », de surcharger les ressources système et d'augmenter la latence.

Envoyez l’en-tête X-Device-Info pour chaque requête v2 de l’API REST.

Même lorsque la requête provient d’un serveur pour le compte d’un appareil, la valeur de l’en-tête X-Device-Info doit refléter les informations réelles de l’appareil de diffusion en continu.

Risques classés comme provenant d’une plateforme inconnue et traités comme non sécurisés, devenant ainsi soumis à des règles plus restrictives, telles que des TTL d’authentification plus courtes.

De plus, certains champs, comme connectionIp et connectionPort, sont obligatoires pour des fonctions comme l’authentification de base à domicile de Spectrum.

Calculez et stockez un identifiant d’appareil stable qui ne change pas lors des mises à jour ou des redémarrages pour l’en-tête AP-Device-Identifier.

Pour les plateformes sans identifiant matériel, générez un identifiant unique à partir des attributs de l’application et conservez-le.

Risque de perte d’authentification lorsque l’identifiant de l’appareil change.

Assurez-vous de n’envoyer que les paramètres et en-têtes attendus de l’API REST v2.

Risque de déclencher des réponses d'erreur HTTP 400 « Bad Request », de surcharger les ressources système et d'augmenter la latence.

Conditions requises

Risques

Gérez les codes d’erreur améliorés de manière appropriée et utilisez le champ d’action pour déterminer les étapes de correction nécessaires.

Seul un nombre limité de codes d’erreur améliorés justifie une nouvelle tentative, alors que la plupart nécessitent d’autres résolutions, comme spécifié dans le champ d’action.

La plupart des codes d’erreur améliorés répertoriés dans la documentation Codes d’erreur améliorés - API REST V2 peuvent être entièrement évités s’ils sont correctement gérés pendant la phase de développement avant le lancement de l’application.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Risque de dysfonctionnement de l’application cliente en raison d’une gestion manquante des codes d’erreur améliorés, ce qui entraîne des messages d’erreur flous, des conseils d’utilisation incorrects ou un comportement de secours incorrect.

Différenciez la gestion des réponses d’erreur HTTP (par exemple, 400, 401, 403, 404, 405, 500) et des réponses de succès (par exemple, 200, 201) qui contiennent des payloads de codes d’erreur améliorés, comme expliqué ci-dessus.

Seul un nombre limité de codes d’erreur HTTP justifie une nouvelle tentative, alors que la plupart nécessitent d’autres résolutions.

La plupart des réponses d’erreur HTTP peuvent être entièrement évitées si elles sont correctement gérées pendant la phase de développement avant le lancement de l’application.

Risque de surcharger les ressources système, d’augmenter la latence et de déclencher potentiellement des réponses d’erreur HTTP 429 « Too many requests ».

Risque de dysfonctionnement de l’application cliente en raison d’une gestion manquante des codes d’erreur améliorés, ce qui entraîne des messages d’erreur flous, des conseils d’utilisation incorrects ou un comportement de secours incorrect.

Conditions requises

Risques

Développez et testez l’application à l’aide des environnements hors production Adobe Pass Authentication officiels :

• Préproduction
• Release-Staging

Effectuez une assurance qualité (QA) approfondie dans ces environnements avant de passer en version de production.

Les applications clientes ne doivent pas passer en version de production sans avoir d’abord effectué la validation de bout en bout dans les environnements hors production.

Risques de lancement avec des défauts critiques et majeurs.

L’absence d’un chemin de débogage court et efficace peut empêcher l’assistance et l’ingénierie Adobe d’intervenir rapidement.

Pratiques

Risques

Vérifiez de manière proactive la validité du jeton d’accès pour l’actualiser après expiration.

Assurez-vous que tout mécanisme de reprise permettant de gérer les erreurs HTTP 401 « Non autorisé » actualise d’abord le jeton d’accès avant de retenter la requête d’origine.

Risques déclenchant des réponses d’erreur HTTP 401 « Non autorisé », surchargeant les ressources système et augmentant la latence.

Pratiques

Risques

Stockez la réponse de configuration en mémoire ou dans un espace de stockage persistant pendant une courte période (par exemple, 3 à 5 minutes) afin d’améliorer les performances et de minimiser les appels v2 inutiles de l’API REST.

Risque de surcharger les ressources système et d’augmenter la latence.

Pratiques

Risques

Validez le code d’authentification envoyé par le biais de l’entrée utilisateur sur la deuxième application secondaire (écran) avant d’appeler l’API /api/v2/authenticate dans les conditions suivantes :

Authentification effectuée dans l’application secondaire (écran) avec mvpd présélectionné

• Utilisez la Reprendre la session d’authentification - POST /api/v2/{serviceProvider}/sessions/{code}

Authentification effectuée dans l’application secondaire (écran) sans mvpd présélectionné

• Utilisez l’option Récupérer la session d’authentification - GET /api/v2/{serviceProvider}/sessions/{code}

L’application cliente recevait une erreur si le code d’authentification fourni était mal saisi ou si la session d’authentification arrivait à expiration.

Risque diverses réponses d'erreur et problèmes de workflow lors de l'authentification.

Assurez-vous que l’application cliente peut gérer plusieurs profils en invitant l’utilisateur à sélectionner un profil ou en appliquant une logique personnalisée, telle que la sélection automatique du profil ayant la période de validité la plus longue.

Risque de dysfonctionnement de l’application cliente en raison d’une prise en charge manquante côté application cliente.

Prendre en charge les flux non basiques si l’activité de l’application cliente l’exige :

• Flux d’accès dégradés (fonctionnalité Premium)
• Flux d’accès temporaires (fonctionnalité Premium)
• Flux d’accès à authentification unique (fonctionnalité standard)

Risque de créer une expérience utilisateur loin d’être idéale.

Pratiques

Risques

Affichez des commentaires utilisateur clairs si une décision de préautorisation est refusée, en utilisant les messages fournis par les MVPD ou Adobe via des codes d’erreur améliorés.

Risque de créer une expérience utilisateur loin d’être idéale.

Pratiques

Risques

Validez les jetons multimédias à l’aide de la bibliothèque Vérificateur de jetons multimédias.

Risques de fraude tels que l'arrachage de flux.

Affichez des commentaires utilisateur clairs si une décision d’autorisation est refusée, en utilisant les messages fournis par les MVPD ou Adobe via des codes d’erreur améliorés.

Risque de créer une expérience utilisateur loin d’être idéale.

Pratiques

Risques

Évitez d’appeler automatiquement (par programmation) l’API de déconnexion dans des scénarios tels que le refus de la préautorisation ou de l’autorisation, car l’API de déconnexion ne doit être appelée qu’en réponse à une demande directe de l’utilisateur.

Risque de dérouter l’utilisateur en raison de l’échec de l’authentification.

Pratiques

Risques

Réutilisez le code de l’API REST v1 pour calculer l’identifiant de l’appareil et les informations sur l’appareil avec des ajustements mineurs, mais assurez-vous d’envoyer uniquement les paramètres et en-têtes attendus de l’API REST v2.

Réutilisez le code de l’API REST v1 pour appeler l’API DCR afin de récupérer un jeton d’accès.

-

Pratiques

Risques

Vérifiez que les flux de base suivants sont testés sur les appareils et plateformes :

Flux d’authentification

• Scénario d’authentification de l’application de Principal (écran)
• Scénario d’authentification de l’application Secondaire (écran)

(Facultatif) Flux de préautorisation

• Scénario de décisions d’autorisation de test
• Test du scénario de refus de décisions

Flux d’autorisation

• Scénario de décisions d’autorisation de test
• Test du scénario de refus de décisions

Flux de déconnexion

Testez également d’autres flux d’accès, le cas échéant :

• Flux d’accès dégradés (fonctionnalité Premium)
• Flux d’accès temporaires (fonctionnalité Premium)
• Flux d’accès à authentification unique (fonctionnalité standard)

Couverture des principales intégrations MVPD (couvrant les fournisseurs les plus utilisés).

Risque de défaillances imprévues dans la production, notamment sur des plateformes moins fréquemment testées ou des flux rares comme des scénarios négatifs.

Utilisez le site web Adobe Developer.

-

Phase

Obligatoire

(Fortement) Recommandé

Mettre en cache les informations d’identification du client

Mettre en cache les jetons d’accès

Valider et actualiser les jetons d’accès

Minimiser les récupérations de réponse de configuration

Réponse de configuration du cache

Réglage fin du mécanisme d’interrogation

parties du cache des profils

Prise en charge de plusieurs profils

Prise en charge de la fonctionnalité de dégradation (si les besoins de l’entreprise)

Prise en charge de la fonctionnalité TempPass (si les besoins de l’entreprise)

Prise en charge de la fonctionnalité d’authentification unique (si les besoins de l’entreprise)

Autorisation du cache décisions de préautorisation

réglage fin du mécanisme de reprise

Améliorer l’expérience utilisateur en utilisant des codes d’erreur pour les décisions de préautorisation refusées

Récupérer la décision d’autorisation lorsque l’utilisateur demande le réglage fin du mécanisme de lecture

reprise

Améliorez l’expérience utilisateur en utilisant des codes d’erreur pour la validation des décisions d’autorisation refusées

Jeton multimédia

Implémenter l’API de déconnexion pour permettre aux utilisateurs de se déconnecter manuellement

Évitez d’appeler automatiquement l’API de déconnexion

Obligatoire

(Fortement) Recommandé

Respecter les spécifications des en-têtes obligatoires

Réutilisation du code de l’API REST v1

Implémenter une gestion des erreurs améliorée

Implémenter la gestion des erreurs HTTP

-