API De plateforme numérique - Bonnes pratiques d’API

Nous sommes ravis que vous profitiez de notre plateforme en saisissant des données brutes, en vous raccordant à vos propres pièces du puzzle de distribution de publicités ou en vous appuyant sur notre infrastructure. Il existe quelques règles de base qui vous permettront de disposer de la meilleure expérience possible et de préserver l’intégrité de vos applications à mesure que notre API évolue. Restez en contact avec votre consultant en implémentation lorsque vous commencez à créer.

API Dos

Récupérez uniquement les objets dont vous avez besoin.

Obtenir plusieurs objets par ID

La plupart des services prennent en charge la récupération de plusieurs objets spécifiques par ID. Pour ce faire, vous ajoutez une liste d’ID séparés par des virgules à la chaîne de requête. Par exemple, la requête suivante retourne uniquement les éditeurs avec les ID spécifiés.

$ curl -b cookies -c cookies 'https://api.appnexus.com/publisher?id=2,3,5,8,13,21'

Filtrer vos résultats

Le filtrage vous permet de spécifier un sous-ensemble d’objets à retourner. Par exemple, l’appel suivant retourne uniquement les éléments de ligne qui ont l’état "active" :

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?state=active'

Pour les champs de type int, double, date ou money, vous pouvez ajouter min_ ou max_ au filtre. Par exemple, la requête suivante retourne uniquement les éléments de ligne qui ont été modifiés à partir du 1er janvier 2013.

$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?min_last_modified=2019-01-01+00:00:00'

Si votre appel d’API retourne une erreur indiquant « La demande a échoué en raison d’un problème de délai d’expiration ou de mémoire », vous pouvez ajouter add_mappings=false à vos paramètres de requête. L’ajout de ce paramètre retourne uniquement les objets API de niveau supérieur, mais pas leurs enfants imbriqués.

Par exemple,

$ curl -b cookies -c cookies "https://api.appnexus.com/publisher?id=2,3,5,8,13,21&add_mappings=false"

Paginer vos résultats

Vous devez écrire votre application pour tirer parti de notre prise en charge de la pagination. Vous pouvez paginer les résultats en spécifiant start_element et num_elements dans la chaîne de requête de la GET requête. Par exemple, la requête suivante retourne les 50 premiers objets dans la réponse :

$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=50'

Pour récupérer les 50 suivants, vous devez simplement définir start_element=50.

Limiter vos appels

Le nombre de demandes que vous pouvez effectuer sur nos API par minute est limité. Si vous dépassez la limite de limitation, l’API répond avec le code de réponse HTTP 429 (Trop de requêtes) ainsi qu’un message d’erreur dans le contenu de la réponse. Nous renvoyons également un en-tête de réponse avec un Retry-After champ qui spécifie le nombre de secondes à attendre avant de tenter d’autres appels d’API.

Si vous effectuez des appels d’API à l’aide de curl, vous pouvez récupérer l’en-tête de réponse en incluant le paramètre -v dans votre requête.

curl -b cookies -v 'https://api.appnexus.com/advertiser
 
> GET /advertiser HTTP/1.1
> Host: api-test.appnexus.com
> User-Agent: curl/7.43.0
> Accept: */*
...
< Retry-After: 31
< X-Route: /advertiser
< X-Route-Time: 86
...

Dans ce cas, vous pouvez réessayer votre demande en 31 secondes (valeur du Retry-After champ).

Si vous appelez l’API à partir d’un script, vous devez case activée pour le code de réponse 429 lorsque vous effectuez vos appels d’API. Si vous recevez ce code, veillez pendant la durée retournée par le Retry-After champ de l’en-tête de réponse. Après avoir mis en veille pendant la durée spécifiée, votre script peut continuer.

Il existe également une limite de demandes simultanées de 15 demandes à la fois. Une limite supérieure à cette limite renvoie un code HTTP 200, mais avec une charge utile d’erreur.

Pour plus d’informations sur les limites de débit, consultez Contraintes d’utilisation de l’API .

Mettre à jour des tableaux avec "append=true"

Lors de la mise à jour des valeurs de tableau avec l’API, les valeurs de tableau d’un objet sont remplacées par les valeurs fournies dans la PUT requête. Cela est parfait si le comportement prévu consiste à effacer les valeurs d’un tableau et à les remplacer par vos données mises à jour. Toutefois, un indicateur peut être utilisé pour ajouter des données à un tableau plutôt que de le remplacer. Cela est particulièrement utile lors de la mise à jour de tableaux très longs. Le paramètre append=true de requête peut être ajouté à une PUT requête pour définir une mise à jour en mode d’ajout.

Pour notre exemple, supposons que nous disposions d’un objet profil simple avec le tableau suivant country_targets :

Objet de profil, avant la mise à jour

// Before Append
{
        "profile": {
                "code": "Test Profile",
                "country_targets": [
                {
                  "country": "US",
                  "name": "United States"
            }
          ]
        }
}

Si nous devions utiliser append=true dans l’appel PUT à la mise à jour de cet objet, nous pourrions utiliser les données JSON suivantes sans crainte de remplacer les données existantes country_targets de notre profil :

Données de mise à jour JSON

// Update Object
{
    "profile": {
        "country_targets": [
                        {
                                "country": "GR",
                                "name": "Greece"
                }
        ]
    }
}

Nous allons utiliser la commande CURL suivante (en remplaçant par <profile_ID> la valeur appropriée).

Exemple CURL

$ curl -b cookie -c cookie -X PUT -s -d '@json/profile.json' "https://api.appnexus.com/profile?id=<profile_ID>&append=true"

En conséquence. notre objet de profil serait mis à jour pour refléter les éléments suivants :

Objet de profil résultant

// After Append
{
        "profile": {
                "code": "Test Profile",
                "country_targets": [
                {
                        "country": "US",
                        "name": "United States"
            },
                        {
                                "country": "GR",
                                "name": "Greece"
                }
        ]
        }
}

Utiliser un point de terminaison d’API piloté par la configuration

Assurez-vous que vous pouvez modifier facilement l’URL de base de l’API. Dans l’exemple ci-dessous, l’URL de l’API est définie en tant que variable et peut être utilisée dans la base de code. Si cette URL doit changer, elle peut être modifiée à un emplacement unique.

$config = "https://api.appnexus.com";

Créer un wrapper d’API

La centralisation du code dans lequel vous envoyez des demandes et gérez les réponses est une bonne pratique. Cela vous permettra d’effectuer la journalisation, la gestion des erreurs et plus encore dans un seul emplacement.

Gardez vos rapports maigres et concentrés

Voici quelques conseils pour éviter que vos rapports soient inutilement volumineux ou qu’ils prennent beaucoup de temps à traiter :

• Raccourcissez le report_interval (c’est-à-dire, de la durée de vie à last_48_hours)
• Ajouter d’autres filtres de niveau supérieur (par exemple, pour un éditeur, un annonceur, un élément de ligne spécifique, etc.)
• Évitez de combiner des dimensions granulaires côté achat et côté vente (c’est-à-dire, créatif et placement), car cela augmente le nombre de lignes de façon exponentielle. Si vous devez créer des rapports sur ces combinaisons, envisagez d’utiliser des flux de création de rapports en bloc ou desflux de données au niveau du journal.

Si vous devez extraire des rapports très volumineux, suivez les instructions fournies dans Pagination des rapports.

Autoriser des champs supplémentaires sur les réponses

À mesure que notre équipe d’API implémente de nouvelles fonctionnalités, il est nécessaire d’inclure de nouveaux champs sur différents services d’API. Votre intégration doit être suffisamment flexible pour gérer des champs supplémentaires sur chaque service qui n’ont pas été retournés précédemment.

Soyez conscient des changements cassants

Nos services changent continuellement à mesure que nous ajoutons de nouvelles fonctionnalités, mais nous faisons de notre mieux pour créer une stabilité afin que les applications que nos clients génèrent sur notre API puissent également s’adapter correctement.

Lorsque nous introduisons un changement cassant, nous prenons en charge deux versions de l’API en production, l’une avec et l’autre sans changement cassant, pendant 60 jours. Nous annoncerons ces modifications dans nos notes de publication de l’API. Pour plus d’informations sur ce qui constitue un changement cassant, consultez notre stratégie changements cassants.

Gardez à l’esprit les limites des objets

Nous limitons le nombre d’objets que chaque membre peut créer et utiliser sur la plateforme. Cette limite inclut les objets inactifs et inutilisés (tels que les éléments de ligne définis sur des status inactifs, les placements qui n’ont jamais fourni d’impression, etc.). Vous devez utiliser le service de limite d’objets pour afficher vos limites et surveiller de manière proactive votre utilisation.

Soyez attentif à la planification de votre processus

Si possible, planifiez vos processus afin qu’ils ne se chevauchent pas. S’il n’est pas nécessaire pour l’entreprise d’effectuer vos opérations en bloc pendant les heures d’ouverture, essayez de planifier ces processus pendant les heures creuses afin d’optimiser votre utilisation de l’API tout au long de la journée. N’oubliez pas qu’un certain nombre d’appels EN LECTURE et ÉCRITURE vous sont alloués par minute. Essayez de tirer parti des moments où vous n’effectuez pas d’appels à l’API afin de disposer d’une marge d’attente supplémentaire aux moments où vous en avez besoin, et de hiérarchiser vos opérations qui respectent le temps.

Ne pas faire de l’API

Ne supposez pas qu’un appel d’API a réussi

Tous les appels d’API réussis reçoivent une réponse contenant la "status" valeur ."OK" Si la réponse ne contient pas cette status, l’appel a échoué pour une raison quelconque. Si est "status""error", un message d’erreur est inclus dans la réponse. Voici un exemple de réponse réussie.

{
   "response": {
      "status": "OK",
      "line-item": {
         ...
      }
   }
}

Ne vous fiez pas aux champs par défaut

Il est recommandé de transmettre les valeurs de champ souhaitées au lieu de s’appuyer sur les valeurs de champ par défaut. Si les valeurs par défaut changent et que vous utilisez les valeurs par défaut, vous pouvez rencontrer des résultats inattendus.

Ne pas effectuer de mises à jour inutiles

Lors de la mise à jour d’objets, vous pouvez éviter d’effectuer des mises à jour inutiles en transmettant uniquement les champs qui changent à l’API. Une bonne façon de vous assurer que cette pratique consiste à mettre en cache vos GET appels, à comparer le cache aux modifications que vous souhaitez apporter, puis à effectuer PUT des appels uniquement pour ce qui est différent.

Si vous avez besoin de mettre à jour tous les objets d’un ensemble ( par instance, en mettant à jour sur cost_cpm tous les emplacements d’un site - vous ne devez pas effectuer d’itération au sein de chacun des objets effectuant des PUT appels aveuglément. Au lieu de cela, émettez un GET appel pour récupérer l’état actuel de chacun des objets de votre jeu. Si possible, veillez à utiliser les fonctionnalités de filtrage et de tri documentées dans La sémantique de l’API pour récupérer uniquement les objets qui auront besoin d’une mise à jour. Comparez l’état actuel des objets retournés à l’état souhaité et émettez un PUT uniquement pour les objets qui nécessitent réellement une mise à jour.

Ne pas s’authentifier inutilement

Lorsque vous vous authentifiez, votre jeton reste valide pendant 2 heures. Vous n’avez pas besoin de vous authentifier à nouveau dans ce délai. Si vous vous authentifiez à nouveau, . Notez la limitation suivante : l’API vous permet de vous authentifier correctement 10 fois par période de 5 minutes. Toutes les tentatives d’authentification suivantes dans ces 5 minutes entraînent une erreur.

Pour obtenir des instructions d’authentification, consultez Service d’authentification.

Ne pas extraire tous les rapports en même temps

Cela peut entraîner une surcharge du back-end de création de rapports, ce qui entraîne des retards dans les rapports et peut même avoir un impact sur les rapports exécutés plus tard dans la journée. Pour plus d’informations, consultez la section Limitation des rapports de la page Service de rapports .

N’effectuez pas de demandes en bloc au service de création de rapports

Si votre architecture appelle plusieurs demandes du service de création de rapports par heure ou par jour, examinez les rapports de niveau supérieur avec plus de données pour voir si vous pouvez obtenir les données dont vous avez besoin avec moins d’appels à l’API.

Par exemple, si vous demandez des rapports horaires pour tous les annonceurs et éditeurs de votre réseau, déterminez si l’utilisation du rapport Analyse réseau répond à vos besoins. Envisagez de l’utiliser comme alternative à des demandes individuelles pour les rapports Analytics annonceur ou Publisher Analytics , ce qui garantit une meilleure correspondance avec votre cas d’usage.

Pour plus d’informations sur tous les rapports disponibles et leurs champs, consultez la documentation de l’API sur Reporting Service.