API de plateforme numérique - Sémantique d’API

Cette page explique la sémantique de notre API REST. Il inclut des informations sur :

• Comment interroger un service sur lui-même : quels champs il prend en charge, quels champs peuvent être filtrés.
• Comment obtenir uniquement les informations souhaitées en filtrant et en triant.
• La « forme » de nos réponses JSON dans différents scénarios.

Ce document part du principe que vous avez terminé le processus d’intégration des API.

Protocole HTTP

L’API De plateforme numérique prend en charge le protocole HTTP version 1.1 ou ultérieure. Bien que certains appels puissent fonctionner avec la version 1.0 déconseillée, cela n’est pas garanti. Vérifiez que votre client communique avec au moins la version 1.1.

Points de terminaison d’API

L’URL du point de terminaison de l’API de production est : https://api.appnexus.com. Notez que l’accès non sécurisé à l’API de produit (HTTP) n’est pas disponible.

Les modifications apportées avec cette API affectent l’environnement de production. Seuls les utilisateurs autorisés doivent modifier les informations ou les paramètres dans cet environnement.

Sémantique REST

Nos services d’API sont RESTful. REST (Representational State Transfer) est un type d’architecture logicielle dans laquelle les demandes modélisent la communication entre un navigateur web et un serveur web. Voici les méthodes REST centrales utilisées dans nos services d’API et leurs utilisations :

Lorsque vous effectuez une POST requête ou PUT , vous devez inclure un fichier JSON avec les données à créer ou à mettre à jour.

$ curl -b cookies 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
                }
            ],
            ...
        }
    }
}

$ cat creative_update
{
    "creative": {
        "pixels": [
            {
                "format": "url-js",
                "url":"https://12.19.232.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
            },
            {
                "id": 196,
                "format": "url-js",
                "url": "https://50.18.232.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}"
            }
        ]
    }
}

$ curl -b cookies -X PUT -d @creative_update 'https://api.appnexus.com/creative?id=503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}
                     &ref=${REFERER_URL}&campaign_id=147"
                },
                {
                    "id": 197,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url":"https://12.13.234.312/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}"
                }
            ],
            ...
        }
    }
}

Utilisation de cURL

Dans notre documentation, nous utilisons curl pour effectuer des requêtes HTTP. Curl est un outil en ligne de commande permettant de transférer des fichiers avec une syntaxe d’URL, prenant en charge FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAPS, etc. Des exemples de scripts ont été fournis sur chaque page wiki d’API pour illustrer la structure des curl commandes dont vous aurez besoin pour exécuter les services d’API Xandr. En outre, vous trouverez ci-dessous un exemple de création d’une requête générique POST . Cet exemple utilise le service d’authentification :

$ curl -b cookies -c cookies -X POST -d @auth.json 'https://api.appnexus.com/auth'

Filtrage et tri

La plupart des services d’API prennent en charge le filtrage et le tri. Le filtrage vous permet de spécifier un sous-ensemble d’objets à retourner. Le tri vous permet de contrôler l’ordre des objets retournés.

Obtenir plusieurs objets par ID

Vous pouvez obtenir plusieurs objets spécifiques par ID en passant une liste d’ID séparés par des virgules. L’objet de résultat contient un tableau contenant uniquement ces objets spécifiques. Dans l’exemple ci-dessous, nous demandons au service campagne uniquement les campagnes avec les ID 1, 2 et 3.

$ curl -bc -cc 'https://api.appnexus.com/campaign?id=1,2,3
{ 
  "response" : {
     "count" : 3,
     "status" : "OK",
     "campaigns" : [ ... ]
  }
}
      

Filtrer par ID

Transmettez un paramètre de chaîne de requête pour le champ avec une liste d’ID séparés par des virgules.

Exemples

Demander toutes les campagnes pour certains éléments de ligne

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=40&line_item_id=1,2,3' 

Demander à certains annonceurs

$ curl -b cookies 'https://api.appnexus.com/advertiser?id=3'

Filtrer par valeurs min et max

Les champs du type , , ou money peuvent être filtrés par min et max. datedoubleint Par exemple :

$ curl -b cookies 'https://api.appnexus.com/campaign?min_id=47'
$ curl -b cookies 'https://api.appnexus.com/campaign?min_advertiser_id=20'

Les champs du type date peuvent également être filtrés par nmin et nmax . Le nmin filtre vous permet de rechercher des dates qui se trouvent null ou après la date spécifiée, et le nmax filtre vous permet de rechercher des dates qui sont soit ou antérieures null à la date spécifiée. Par exemple :

$ curl -b cookies 'https://api.appnexus.com/campaign?nmax_start_date=2012-12-20+00:00:00'
$ curl -b cookies 'https://api.appnexus.com/campaign?nmin_end_date=2013-01-01+00:00:00'

Notez la syntaxe date/heure requise dans l’exemple précédent : AAAA-MM-JJ+HH :MM :SS

Une autre option de filtrage par date consiste à utiliser le min_last_modified filtre :

$ curl -b cookies 'https://api.appnexus.com/campaign?min_last_modified=2017-10-27+21:00:00'

Filtrer par noms de champs

Pour limiter la réponse à des champs spécifiques d’un objet, transmettez le fields paramètre de chaîne de requête avec une liste de noms de champs séparés par des virgules. Par exemple :

$ curl -b cookies "https://api.appnexus.com/user?current&fields=username,user_type,id"
{
    "response":{
        "status":"OK",
        "count":1,
        "start_element":0,
        "num_elements":100,
        "user":{
            "id":14311,
             "username":"rloveland",
             "user_type":"admin"
        }
    }
}
 
    

Filtres divers sur le champ

Nous prenons en charge les filtres supplémentaires basés sur les champs suivants sur les réponses d’API :

• not_*
• like_*
• min_*
• max_*
• nmin_*
• nmax_*
• having_*
• having_min_*
• having_max_*

Exemple

$ curl -b cookies 'https://api.appnexus.com/placement?like_[fieldName]=partialValue'

Recherche

Certains services prennent en charge search en tant que paramètre de chaîne de requête pour rechercher l’ID ou le nom. Par exemple :

$ curl -b cookies 'https://api.appnexus.com/placement?search=17'

Tri

Pour trier, utilisez le sort paramètre de chaîne de requête et transmettez une liste de champs que vous souhaitez trier et si vous souhaitez qu’ils soient croissants (asc) ou décroissants (desc). Par exemple :

$ curl -b cookies 'https://api.appnexus.com/campaign?advertiser_id=1&sort=id.desc'

Pagination

Pour pager, utilisez les start_element paramètres et num_elements . Si num_elements n’est pas fourni, la valeur par défaut est 100 (qui est également la valeur maximale).

$ curl -b cookies 'https://api.appnexus.com/campaign?start_element=20&num_elements=10'

Ajouter sur PUT

En incluant append=true dans la chaîne de requête d’un PUT appel, un utilisateur peut mettre à jour uniquement un objet enfant particulier au lieu de remplacer tous les objets enfants. En d’autres termes, au lieu de remplacer un tableau entier par un nouveau sur un PUT appel, vous pouvez utiliser append=true sur la chaîne de requête pour ajouter un seul élément à un tableau long.

Dans cet exemple, nous allons utiliser append=true sur un PUT appel pour basculer l’indicateur is_available d’un objet dans le member_availabilities tableau du service de plug-in. Sans l’indicateur append=true sur la chaîne de requête, le nouvel élément remplacerait l’ensemble du tableau. Dans cet exemple, il est uniquement ajouté.

Examinons d’abord l’objet que nous allons modifier (ces exemples utilisent jq pour découper et dés le JSON). Les deux disponibilités sont définies sur true:

Nous allons envoyer le code JSON suivant pour désactiver l’indicateur is_available sur l’un member_availability des objets :

$ cat plugin-update.json
{
    "plugin" : {
        "developer" : {
            "id" : 1
        },
         "member_availabilities" : [
            {
                "is_available" : false,
                 "id" : 4
            }
        ],
         "name" : "ccc"
    }
}

Normalement, l’envoi du code JSON ci-dessus sur un PUT appel remplace l’ensemble member_availabilities du tableau. Toutefois, cette fois, nous allons ajouter "append=true" à la chaîne de requête de l’appel. Cela indique à l’API de modifier uniquement l’objet dont id est 4. Nous pouvons vérifier que cela est fait en inspectant la sortie.

$ curl -bc -X PUT -d @plugin-update.json 'https://api.appnexus.com/plugin?id=13&append=true' | jq '.response.plugin.member_availabilities'
[
  {
    "is_available": false,
    "id": 4
  },
  {
    "is_available": true,
    "id": 7
  }
]

Structure de base JSON

Vous trouverez ci-dessous la syntaxe des composants d’un objet JSON et leur signification.

Objet :

{. . . }

Un tableau :

[. . . ]

Une chaîne :

". . ."

Associez une clé à une valeur de chaîne alphanumérique :

"key":"string"

Associez une clé à une valeur numérique :

"key":int

Exemple qui les regroupe :

{
    "campaign": {
        "name": "my campaign",
        "id": 1434,
        "creatives": [
                {
                    "id": 4162,
                    "state": "active"
                }
            ],
}
}

Types de champs JSON

POST les requêtes et PUT nécessitent des données JSON . Pour PUT les demandes, seuls les champs JSON inclus dans une demande sont mis à jour. Tous les autres champs resteront inchangés.

Différents champs nécessitent différents types de valeurs. Le tableau des types ci-dessous étend ceux définis dans la norme JSON.

Exemple pour le type d’objet

"brand": {
"id": 466,
"name": "PKR"
}

Exemple pour le type de tableau

"members" : [
{
"id": 1234,
"member_use_deal_floor": true,
"member_ask_price": 2.15,
"name": "Buyer 1"
},
{
"id": 5561,
"member_use_deal_floor": true,
"member_ask_price": 2.25,
"name": "Buyer 2"
}
]

Comment et pourquoi les API de création de rapports sont différentes ?

Les API de création de rapports disponibles via le service de rapports fonctionnent différemment de nos autres API. Ils ont leur propre flux de requête et de réponse à plusieurs étapes. Cela est nécessaire, car ils traitent de grandes quantités de données ; ce traitement doit être effectué de manière asynchrone.

Pour obtenir des instructions sur la façon de récupérer des rapports, consultez service de rapports.

Pour obtenir un tutoriel qui explique comment utiliser efficacement nos API de création de rapports, consultez Pagination de rapports.

Remarque sur les traits de soulignement et les traits d’union

Les champs et les valeurs JSON utilisent des traits de soulignement, par exemple . audit_type_direct

Les noms de service d’API dans les URL sont traits d’union, par exemple . https://api.``appnexus``.com/insertion-order

Codes de réponse

Tous les services d’API retournent des données JSON . Lorsque les appels de service réussissent, la réponse JSON inclut un "status" champ défini sur "OK". La réponse aux appels et POSTPUT inclut également l’ID de l’objet approprié, ainsi que tous les attributs pertinents de cet objet. Chaque réponse inclut un "dbg_info" objet qui transmet des informations sur l’appel et la réponse d’API destinés à un usage interne Xandr uniquement et pouvant être demandés lors d’une demande de support.

Messages d’erreur

Quand une entrée non valide est envoyée à l’API (par exemple, un mot de passe incorrect), une réponse JSON est retournée avec "error" les champs et "error_id" .

$ cat auth
{
  "auth": {
     "username":"user1",
     "password":"Wr0ngP@ss"
  }
}
$ curl -b cookies -c cookies -X POST -d @auth 'https://api.appnexus.com/auth'
{
    "response": {
        "error_id": "NOAUTH"
        "error": "No match found for user\/pass",
        "dbg_info": {
            ...
        }
    }
}

Le "error" champ est utile à des fins de débogage, car il contient une description détaillée de l’erreur. Le "error_id" champ peut être utilisé par programme, comme décrit dans le tableau ci-dessous.

Voir aussi

• Contraintes d’utilisation de l’API
• Bonnes pratiques relatives aux API