REST API v2-Checkliste rest-api-v2-checklist

Anforderungen

Risiken

Verwenden Sie eine registrierte Anwendung mit dem Umfang der REST-API v2.

Risiken, die HTTP 401-Fehlerantworten „nicht autorisiert“ auslösen, Systemressourcen überlasten und die Latenz erhöhen.

Speichern Sie die Client-Anmeldeinformationen in einem persistenten Speicher und verwenden Sie sie für jede Zugriffstoken-Anfrage erneut.

Riskiert einen Authentifizierungsverlust, wenn die Client-Anmeldeinformationen neu generiert werden.

Speichern Sie die Zugriffs-Token in einem persistenten Speicher und verwenden Sie sie bis zu ihrem Ablauf erneut.

Fordern Sie nicht für jeden REST API v2-Aufruf ein neues Token an. Aktualisieren Sie die Zugriffstoken erst, wenn sie ablaufen.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Anforderungen

Risiken

Rufen Sie die Konfigurationsantwort nur ab, wenn Sie vor der Authentifizierungsphase den Benutzer auffordern müssen, seinen MVPD (TV-Anbieter) auszuwählen.

Es ist nicht erforderlich, die Konfigurationsantwort abzurufen, wenn:

• Der Benutzer ist bereits authentifiziert.
• Dem Benutzer wird temporärer Zugriff angeboten.
• Die Benutzerauthentifizierung ist abgelaufen, aber der Benutzer kann aufgefordert werden, zu bestätigen, dass er weiterhin Abonnent der zuvor ausgewählten MVPD ist.

Risiken, die Systemressourcen zu überlasten und die Latenz zu erhöhen.

Speichern Sie die Auswahl des Pay-TV-Anbieters (MVPD) des Benutzers in einem beständigen Speicher, um sie in allen nachfolgenden Phasen zu verwenden:

• Der Benutzer hat im Konfigurationsantwortspeicher „ID“ für MVPD ausgewählt.
• Der Benutzer hat im Konfigurationsantwortspeicher „displayName“ für MVPD ausgewählt.
• Der Benutzer hat im Konfigurationsantwortspeicher „logoUrl“ für MVPD ausgewählt.

Risiken, die Systemressourcen zu überlasten und die Latenz zu erhöhen.

Anforderungen

Risiken

Starten Sie den Abrufmechanismus unter den folgenden Bedingungen:

Authentifizierung wird innerhalb der primären (Bildschirm-)Anwendung durchgeführt

• Die primäre (Streaming-)Anwendung sollte den Abfragevorgang starten, wenn die Benutzerin oder der Benutzer die endgültige Zielseite erreicht, nachdem die Browser-Komponente die in der Sitzungs-Endpunktanforderung für den Parameter „redirectUrl“ angegebene URL geladen hat.

Authentifizierung wird in einer sekundären (Bildschirm-)Anwendung durchgeführt

• Die primäre (Streaming-)Anwendung sollte den Abfragevorgang starten, sobald der Benutzer den Authentifizierungsprozess einleitet - direkt nach Erhalt der Antwort des Sitzungs-Endpunkts und Anzeige des Authentifizierungs-Codes für den Benutzer.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Beenden Sie den Abrufmechanismus unter den folgenden Bedingungen:

Erfolgreiche Authentifizierung

• Die Profilinformationen des Benutzers wurden erfolgreich abgerufen, wodurch sein Authentifizierungsstatus bestätigt wird. Daher ist keine Abfrage mehr erforderlich.

Authentifizierungssitzung und Code-Ablauf

• Wenn die Authentifizierungssitzung und der Authentifizierungscode ablaufen, muss der Benutzer den Authentifizierungsprozess neu starten, und das Abrufen mit dem vorherigen Authentifizierungscode sollte sofort gestoppt werden.

Neuer Authentifizierungs-Code generiert

• Wenn der Benutzer einen neuen Authentifizierungs-Code anfordert, wird die vorhandene Sitzung ungültig gemacht, und das Abrufen mit dem vorherigen Authentifizierungs-Code sollte sofort gestoppt werden.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Konfigurieren Sie die Häufigkeit des Abrufmechanismus unter den folgenden Bedingungen:

Authentifizierung wird innerhalb der primären (Bildschirm-)Anwendung durchgeführt

• Die primäre (Streaming-)Anwendung sollte alle 3-5 Sekunden oder länger abfragen.

Authentifizierung wird in einer sekundären (Bildschirm-)Anwendung durchgeführt

• Die primäre (Streaming-)Anwendung sollte alle 3-5 Sekunden eine Abfrage durchführen.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Speichern Sie Teile der Profilinformationen des Benutzers im beständigen Speicher, um die Leistung zu verbessern und unnötige REST-API-v2-Aufrufe zu minimieren.

Die Zwischenspeicherung sollte sich auf die folgenden Antwortfelder der Profile konzentrieren:

mvpd

• Die Client-Anwendung kann dies verwenden, um den vom Benutzer ausgewählten TV-Anbieter zu verfolgen und ihn während der Vorautorisierungs- oder Autorisierungsphase weiter zu verwenden.
• Wenn das aktuelle Benutzerprofil abläuft, kann die Client-Anwendung die gespeicherte MVPD-Auswahl verwenden und den Benutzer einfach zur Bestätigung auffordern.

Attribute

• Wird verwendet, um das Benutzererlebnis basierend auf verschiedenen Benutzermetadatenschlüsseln (z. B. ZIP, MaxRating usw.) zu personalisieren.
• Benutzermetadaten werden nach Abschluss des Authentifizierungsflusses verfügbar, daher muss die Client-Anwendung keinen separaten Endpunkt abfragen, um die Benutzermetadaten-Informationen abzurufen, da sie bereits in den Profilinformationen enthalten sind.
• Bestimmte Metadatenattribute können während der Autorisierungsphase aktualisiert werden, je nach MVPD (z. B. Charta) und dem spezifischen Metadatenattribut (z. B. householdID). Daher muss die Client-Anwendung möglicherweise die Profil-APIs nach der Autorisierung erneut abfragen, um die neuesten Benutzermetadaten abzurufen.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Anforderungen

Risiken

Verwenden Sie Entscheidungen zur Vorabautorisierung für die Inhaltsfilterung und niemals für Wiedergabeentscheidungen.

Gefahr der Verletzung vertraglicher Vereinbarungen zwischen Programmer, MVPDs und Adobe.

Risiken, unsere Überwachungs- und Warnsysteme zu umgehen.

Verarbeiten Sie die erweiterten FehlerCodes entsprechend und verwenden Sie das Aktionsfeld, um die erforderlichen Korrekturschritte zu bestimmen.

Nur eine begrenzte Anzahl erweiterter Fehler-Codes rechtfertigt einen erneuten Versuch, während für die meisten alternative Auflösungen wie im Aktionsfeld angegeben erforderlich sind.

Stellen Sie sicher, dass ein Wiederholungsmechanismus, der zum Abrufen von Entscheidungen vor der Autorisierung implementiert wird, nicht zu einer Endlosschleife führt und dass Wiederholungsversuche auf eine angemessene Anzahl begrenzt werden (d. h. 2-3).

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Erfolgreiche Cache-Zulassungsentscheidungen im Speicher, um die Leistung zu verbessern und unnötige REST-API-v2-Aufrufe zu minimieren, da Abonnementaktualisierungen während der Ausführung der Anwendung selten sind.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Anforderungen

Risiken

Erhalten Sie Autorisierungsentscheidungen vor der Wiedergabe - unabhängig davon, ob eine Entscheidung vor der Autorisierung existiert.

Erlauben Sie Streams die unterbrechungsfreie Fortsetzung, selbst wenn das Medien-Token während der Wiedergabe abläuft, und fordern Sie eine neue Autorisierungsentscheidung an, die ein (neues) Medien-Token enthält, wenn der Benutzer seine nächste Wiedergabeanforderung durchführt, unabhängig davon, ob es sich um dieselbe oder eine andere Ressource handelt.

Live-Streams, die über längere Zeiträume laufen, können nach Videovorgängen eine neue Autorisierungsentscheidung anfordern, z. B. nach dem Anhalten von Inhalten, dem Initiieren von Werbeunterbrechungen oder dem Ändern der Konfigurationen auf Asset-Ebene, wenn der MRSS geändert wird.

Gefahr der Verletzung vertraglicher Vereinbarungen zwischen Programmer, MVPDs und Adobe.

Risiken, unsere Überwachungs- und Warnsysteme zu umgehen.

Verarbeiten Sie die erweiterten FehlerCodes entsprechend und verwenden Sie das Aktionsfeld, um die erforderlichen Korrekturschritte zu bestimmen.

Nur eine begrenzte Anzahl erweiterter Fehler-Codes rechtfertigt einen erneuten Versuch, während für die meisten alternative Auflösungen wie im Aktionsfeld angegeben erforderlich sind.

Stellen Sie sicher, dass ein zum Abrufen von Autorisierungsentscheidungen implementierter Wiederholungsmechanismus nicht zu einer Endlosschleife führt und dass Wiederholungsversuche auf eine angemessene Anzahl (d. h. 2-3) begrenzt werden.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Anforderungen

Risiken

Implementieren Sie die Abmelde-API, damit sich Benutzer manuell abmelden können, wodurch ihr authentifiziertes Profil beendet wird, und folgen Sie dem für jedes entfernte Profil angegebenen REST API v2-Aktionsnamen:

• Bei MVPDs, die einen Abmeldeendpunkt unterstützen, muss die Client-Anwendung in einem Benutzeragenten zur angegebenen „URL“ navigieren.
• Bei Profilen vom Typ „appleSSO“ muss die Client-Anwendung den Benutzer anweisen, sich auch auf Partnerebene abzumelden (Systemeinstellungen von Apple).

Risiken durch Fehlfunktion der Client-Anwendung aufgrund fehlender Unterstützung auf der Client-Anwendungsseite.

Anforderungen

Risiken

Senden Sie für REST API v2Anfrage die Kopfzeile „Authorization“.

Risiken, die HTTP 401-Fehlerantworten „nicht autorisiert“ auslösen, Systemressourcen überlasten und die Latenz erhöhen.

Senden Sie für REST API v2-Anfrage den HeaderAP-Device-Identifier“.

Selbst wenn die Anfrage von einem Server im Namen eines Geräts stammt, muss der Kopfzeilenwert AP-Device-Identifier die tatsächliche Kennung des Streaming-Geräts widerspiegeln.

Risiken, die HTTP 400-Fehlerantworten bei „Bad Request“ auslösen, Systemressourcen überlasten und die Latenz erhöhen.

Senden Sie die Kopfzeile X-Device-Info für jede REST API v2-Anfrage.

Selbst wenn die Anfrage von einem Server im Namen eines Geräts stammt, muss der Header-Wert für X-Device-Info die tatsächlichen Streaming-Geräteinformationen widerspiegeln.

Risiken, die als von einer unbekannten Plattform stammend klassifiziert und als unsicher behandelt werden und restriktiveren Regeln unterliegen, wie beispielsweise kürzere Authentifizierungs-TTLs.

Darüber hinaus sind einige Felder, wie die connectionIp des Streaming-Geräts und connectionPort, für Funktionen wie die Basisauthentifizierung von Spectrum obligatorisch.

Berechnen und speichern Sie eine stabile Gerätekennung, die sich nicht über Aktualisierungen oder Neustarts hinweg für die Kopfzeile AP-Device-Identifier ändert.

Bei Plattformen ohne Hardware-Kennung aus Anwendungsattributen eine eindeutige Kennung generieren und beibehalten.

Riskiert einen Authentifizierungsverlust, wenn die Gerätekennung geändert wird.

Vergewissern Sie sich, dass Sie nur die erwarteten Parameter und Header der REST-API v2 senden.

Risiken, die HTTP 400-Fehlerantworten bei „Bad Request“ auslösen, Systemressourcen überlasten und die Latenz erhöhen.

Anforderungen

Risiken

Verarbeiten Sie die erweiterten FehlerCodes entsprechend und verwenden Sie das Aktionsfeld, um die erforderlichen Korrekturschritte zu bestimmen.

Nur eine begrenzte Anzahl erweiterter Fehler-Codes rechtfertigt einen erneuten Versuch, während für die meisten alternative Auflösungen wie im Aktionsfeld angegeben erforderlich sind.

Die meisten erweiterten Fehler-Codes, die in der Dokumentation Erweiterte Fehler-Codes - REST API V2 aufgeführt sind, können vollständig verhindert werden, wenn sie während der Entwicklungsphase vor dem Start der Anwendung korrekt verarbeitet werden.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Es besteht das Risiko, dass die Client-Anwendung aufgrund einer fehlenden Handhabung der erweiterten Fehler-Codes nicht funktioniert, was zu unklaren Fehlermeldungen, falschen Benutzeranleitungen oder falschem Fallback-Verhalten führt.

Unterscheidung zwischen der Verarbeitung von HTTP-Fehlerantworten (z. B. 400, 401, 403, 404, 405, 500) und Erfolgsantworten (z. B. 200, 201), die erweiterte Fehler-Code-Payloads enthalten, wie oben beschrieben.

Nur eine begrenzte Anzahl von HTTP-Fehler-Codes rechtfertigt einen erneuten Versuch, während die meisten alternative Auflösungen erfordern.

Die meisten HTTP-Fehlerantworten können vollständig verhindert werden, wenn sie während der Entwicklungsphase vor dem Start der Anwendung korrekt verarbeitet werden.

Es besteht das Risiko, dass Systemressourcen überlastet werden, die Latenz zunimmt und möglicherweise Fehlerantworten vom Typ „Zu viele Anfragen“ in HTTP 429 ausgelöst werden.

Es besteht das Risiko, dass die Client-Anwendung aufgrund einer fehlenden Handhabung der erweiterten Fehler-Codes nicht funktioniert, was zu unklaren Fehlermeldungen, falschen Benutzeranleitungen oder falschem Fallback-Verhalten führt.

Anforderungen

Risiken

Entwickeln und testen Sie die Anwendung mit den offiziellen produktionsfremden Umgebungen für die Adobe Pass-Authentifizierung:

• Vorserienfertigung
• Release-Staging

Führen Sie in diesen Umgebungen eine gründliche Qualitätssicherung (QA) durch, bevor Sie mit der Veröffentlichung in der Produktionsumgebung beginnen.

Client-Anwendungen dürfen nicht zur Produktionsfreigabe übergehen, ohne zunächst die End-to-End-Validierung in Nicht-Produktionsumgebungen abzuschließen.

Risiken, die mit kritischen und schwerwiegenden Mängeln beginnen.

Ein kurzer und effizienter Debugging-Weg kann den Adobe Support und das Engineering daran hindern, schnell einzugreifen.

Practices

Risiken

Proaktive Überprüfung der Gültigkeit des Zugriffs-Tokens, um es nach Ablauf zu aktualisieren.

Stellen Sie sicher, dass jeder Wiederholungsmechanismus für die Verarbeitung von „nicht autorisierten“ HTTP 401-Fehlern zunächst das Zugriffstoken aktualisiert, bevor Sie die ursprüngliche Anfrage erneut versuchen.

Risiken, die HTTP 401-Fehlerantworten „nicht autorisiert“ auslösen, Systemressourcen überlasten und die Latenz erhöhen.

Practices

Risiken

Speichern Sie die Konfigurationsantwort für einen kurzen Zeitraum (z. B. 3-5 Minuten) im Speicher oder im persistenten Speicher, um die Leistung zu verbessern und unnötige REST-API-v2-Aufrufe zu minimieren.

Risiken, die Systemressourcen zu überlasten und die Latenz zu erhöhen.

Practices

Risiken

Validieren Sie den Authentifizierungscode, der über die Benutzereingabe auf dem Bildschirm der zweiten Anwendung gesendet wurde, bevor Sie die API /api/v2/Authenticate aufrufen, unter den folgenden Bedingungen:

Authentifizierung wird innerhalb der sekundären Anwendung (Bildschirm) mit vorab ausgewähltem mvpd durchgeführt

• Nutzen Sie Authentifizierungssitzung fortsetzen POST /api/v2/{serviceProvider}/sessions/{code}

Authentifizierung wird innerhalb der sekundären (Bildschirm-)Anwendung ohne vorab ausgewählte mvpd durchgeführt

• Verwenden Sie Authentifizierungssitzung abrufen - GET /api/v2/{serviceProvider}/sessions/{code}

Die Client-Anwendung erhält einen Fehler, wenn der angegebene Authentifizierungs-Code falsch eingegeben wurde oder die Authentifizierungssitzung abgelaufen ist.

Dadurch werden verschiedene Fehlerreaktionen und Workflow-Probleme bei der Authentifizierung riskiert.

Stellen Sie sicher, dass die Client-Anwendung mehrere Profile verarbeiten kann, indem Sie den Benutzer entweder zur Auswahl eines Profils auffordern oder eine benutzerdefinierte Logik anwenden, z. B. das Profil mit der längsten Gültigkeitsdauer automatisch auswählen.

Risiken durch Fehlfunktion der Client-Anwendung aufgrund fehlender Unterstützung auf der Client-Anwendungsseite.

Unterstützung nicht grundlegender Flüsse, falls das Client-Anwendungsgeschäft Folgendes erfordert:

• Heruntergestufte Zugriffsflüsse (Premium-Funktion)
• Temporäre Zugriffsflüsse (Premium-Funktion)
• Single-Sign-On-Zugriffsflüsse (Standardfunktion)

Es besteht das Risiko, dass das Benutzererlebnis nicht optimal ist.

Practices

Risiken

Zeigen Sie klares Benutzer-Feedback an, wenn eine Vorautorisierungsentscheidung verweigert wird, indem Sie Nachrichten verwenden, die von MVPDs oder Adobe über erweiterte Fehlercodes bereitgestellt werden.

Es besteht das Risiko, dass das Benutzererlebnis nicht optimal ist.

Practices

Risiken

Validieren von Medien-Token mithilfe der Bibliothek Media Token Verifier.

Risiko von Betrügereien wie Stream-Ripping.

Zeigen Sie klares Benutzer-Feedback an, wenn eine Autorisierungsentscheidung verweigert wird, indem Sie Nachrichten verwenden, die von MVPDs oder Adobe über erweiterte Fehlercodes bereitgestellt werden.

Es besteht das Risiko, dass das Benutzererlebnis nicht optimal ist.

Practices

Risiken

Vermeiden Sie den automatischen (programmgesteuerten) Aufruf der Abmelde-API in Szenarien wie verweigerter Vorautorisierung oder Autorisierung, da die Abmelde-API nur als Antwort auf eine direkte Benutzeranfrage aufgerufen werden sollte.

Es besteht das Risiko, den Benutzer zu verwirren, dass die Authentifizierung fehlschlägt.

Practices

Risiken

Verwenden Sie den Code aus der REST-API v1 zur Berechnung der Gerätekennung und Geräteinformationen mit geringfügigen Anpassungen, stellen Sie jedoch sicher, dass Sie nur die erwarteten Parameter und Kopfzeilen der REST-API v2 senden.

Verwenden Sie Code aus der REST-API v1 zum Aufrufen der DCR-API, um ein Zugriffstoken abzurufen.

-

Practices

Risiken

Stellen Sie sicher, dass die folgenden grundlegenden Flüsse geräte- und plattformübergreifend getestet werden

Authentifizierungsflüsse

• Authentifizierungsszenario für Primäre Anwendungen (Bildschirm)
• Authentifizierungsszenario für Sekundäre Anwendungen (Bildschirm)

(Optional) Vorautorisierungsflüsse

• Szenario für Testgenehmigungsentscheidungen
• Szenario „Ablehnungsentscheidungen testen“

Autorisierungsflüsse

• Szenario für Testgenehmigungsentscheidungen
• Szenario „Ablehnungsentscheidungen testen“

Abmeldevorgänge

Testen Sie außerdem ggf. weitere Zugriffsflüsse:

• Heruntergestufte Zugriffsflüsse (Premium-Funktion)
• Temporäre Zugriffsflüsse (Premium-Funktion)
• Single-Sign-On-Zugriffsflüsse (Standardfunktion)

Abdeckung der wichtigsten MVPD-Integrationen (einschließlich der am häufigsten verwendeten Anbieter).

Risiken durch unvorhergesehene Fehler in der Produktion, insbesondere bei weniger häufig getesteten Plattformen oder seltenen Flüssen wie negativen Szenarien.

Verwenden Sie die Adobe Developer-Website.

-

Phase

Obligatorisch

(dringend empfohlen)

Clientanmeldeinformationen zwischenspeichern

Zugriffstoken zwischenspeichern

Zugriffstoken validieren und aktualisieren

Minimieren des Abrufs von Konfigurationsantworten

Cache-Konfigurationsantwort

Abrufmechanismus: Feinabstimmung

Zwischenspeichern von Profilteilen

Unterstützung mehrerer Profile

Support-Beeinträchtigungsfunktion (bei Geschäftsanforderungen)

Support-TempPass-Funktion (bei Geschäftsanforderungen)

Support-Single-Sign-On-Funktion (bei Geschäftsanforderungen)

Feinabstimmung des Mechanismus für Vorabautorisierungsentscheidungen

Wiederholung) zwischenspeichern

Verbessern des Benutzererlebnisses durch Verwendung von Fehler-Codes für abgelehnte Entscheidungen vor Autorisierung

Abrufen der Autorisierungsentscheidung bei Benutzeranfragen zur Optimierung

Wiedergabe-/Wiederholungsmechanismus

Verbessern Sie das Benutzererlebnis durch die Verwendung von Fehler-Codes für die Validierung von

-Medien-Token

Implementieren der Abmelde-API, damit sich Benutzer manuell abmelden können

Automatisches Aufrufen der Abmelde-API vermeiden

Obligatorisch

(dringend empfohlen)

Pflichtangaben für Kopfzeilen befolgen

Wiederverwenden von Code aus der REST-API v1

Implementieren der erweiterten Fehlerbehandlung

Implementieren der HTTP-Fehlerbehandlung

-