Bonnes pratiques relatives aux 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. Suivez les bonnes pratiques pour vous assurer que vous disposez de la meilleure expérience possible et pour maintenir 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.

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 créatifs actifs :

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?active=true'

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 campagnes qui ont été modifiées à partir du 1er janvier 2013 :

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_last_modified=2013-01-01 00:00:00'

Remarque

Pour chaque service, vous pouvez déterminer quels champs peuvent être filtrés et triables en ajoutant /meta à l’URL du service. Pour plus d’informations, consultez Sémantique de l’API.

Paginer vos résultats

Même si vous n’avez peut-être que 5 créations dans le système, vous devez toujours écrire votre application de manière à tirer parti de la prise en charge de la pagination, car ce nombre est susceptible d’augmenter à l’avenir. Vous pouvez paginer les résultats en spécifiant start_element et num_elements dans la chaîne de requête de la requête GET. Par exemple, la requête suivante retourne les 50 premiers objets dans la réponse :

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

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

Remarque

Le nombre maximal d’objets pouvant être retournés, quelle que soit la pagination, est de 100. Notez que si vous demandez plus de 100 objets, nous retournerons uniquement les 100 premiers objets et ne fournirons pas de message d’erreur. Pour plus d’informations, consultez la page Sémantique de l’API .

Limiter vos appels

Le nombre de demandes que vous pouvez effectuer sur nos API par minute est limité. Nous classons ces limites en limites de débit de lecture et d’écriture. Actuellement, la limite de lecture et d’écriture par défaut est de 1 000 par minute. Ces compteurs sont réinitialisés à la fin de la minute, mais si vous dépassez la limite de limitation, l’API répond avec le code de réponse HTTP 429 (Trop de requêtes). Réessayez la demande dans le nombre de secondes spécifié dans le Retry-After champ de l’en-tête.

Il existe également une limite de demandes simultanées de 20 demandes à la fois. Un dépassement de cette limite renvoie une valeur HTTP 200, mais avec une charge utile d’erreur.

Voici un exemple des valeurs d’en-tête en réponse à une demande qui a dépassé la limite de débit d’un membre.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 16
X-AN-RequestId: 98472eb263664a7b
X-Count-Read: user:101,member:101,serviceHostUser:75,serviceHostMember:75,hostUser:101,hostMember:101,ip:0
X-Count-Write: user:0,member:0,serviceHostUser:0,serviceHostMember:0,hostUser:0,hostMember:0,ip:0
X-Ratelimit-Read: 100
X-Ratelimit-System: 100-Default
X-Ratelimit-Write: 60
Content-Length: 358

Transmettre des valeurs de champ au lieu de s’appuyer sur les valeurs par défaut

Il est recommandé de passer les valeurs de champ souhaitées plutôt que de s’appuyer sur les valeurs 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.

Éviter les mises à jour inutiles

Lors de la mise à jour d’objets, ne transmettez pas les champs qui ne changent pas. Un bon moyen d’éviter cela consiste à mettre en cache vos appels GET, à comparer le cache aux modifications que vous souhaitez apporter, puis à effectuer des appels PUT uniquement pour ce qui est différent.

Éviter l’authentification inutile

Vous pouvez vous authentifier 10 fois dans un délai de 5 minutes. Toutes les tentatives d’authentification suivantes dans ces 5 minutes entraînent une erreur.

Remarque

Lorsque vous vous authentifiez, vous recevez un jeton d’autorisation qui reste actif pendant 2 heures. Il est recommandé de vous authentifier à nouveau uniquement une fois que vous avez reçu les "NOAUTH" error_id dans vos réponses à l’appel. Si vous suivez cette pratique, la restriction ci-dessus ne doit pas avoir d’impact sur votre implémentation.

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

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..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.

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.

Lire l’intégralité du Wiki de l’API avant d’utiliser l’API

Il existe de nombreux conseils, astuces et exemples dans le Wiki de l’API qui seront utiles pour développer votre intégration.

Utiliser des codes d’intégration

Au lieu de stocker les ID Xandr, vous pouvez utiliser les codes d’intégration pour faire référence à l’objet dans l’API. Ces codes doivent être uniques dans un type d’objet et un membre Xandr. L’exemple ci-dessous utilise un code d’intégration pour identifier une campagne.

"creative":{
                "id":6,
                "active":true,
                "member_id": 5,
                "code": your_internal_code
}

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",
      "campaign": {
         ...
      }
   }
}

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

Xandr limite le nombre d’objets que chaque membre peut créer et utiliser sur la plateforme. Cette limite inclut les objets inactifs et inutilisés (par exemple, les campagnes définies 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.