Soumissionnaires - Sémantique d’API

Cette page explique comment utiliser notre API REST de bus d’impression. Il inclut des informations sur :

• Comment s’authentifier
• Comment interroger un service sur lui-même : quels champs il prend en charge, quels champs peuvent être utilisés pour filtrer
• Codes de réponse et erreurs

Protocole HTTP

L’API impression bus de Xandr 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

REST

Les services d’API Xandr 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 les services d’API de Xandr et leurs utilisations :

Dans notre documentation, nous utilisons cURL pour effectuer des requêtes REST. 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, LDAP, LDAPS et FILE. Les exemples de scripts sur chaque page wiki d’API précisent la cURL structure des commandes dont vous aurez besoin pour exécuter les services d’API de Xandr.

Ajouter sur PUT

Pour PUT les demandes, seuls les champs inclus dans le fichier JSON sont mis à jour, sauf dans le cas des tableaux.

Lors de la mise à jour d’un tableau à l’aide PUTde , tous les champs du tableau sont remplacés par le contenu du nouveau tableau que vous chargez, sauf si vous ajoutez ceci à la chaîne de requête de votre requête : "append=true".

Méta-appels

Tous les services de soumissionnaire prennent en charge les méta-appels, qui retournent les champs du service et le type de valeur. Les méta-appels ressemblent à ceci :

$ curl -b cookies -c cookies 'https://api.adnxs.com/SERVICE/meta'

Par exemple (sortie partielle d’un méta-appel) :

            "bidder_id": {
                "type": "int"
            },
            "agent_id": {
                "type": "int"
            },
            "code": {
                "type": "string"
            },
            "active": {
                "type": "boolean"
            }

Limitation des GET enregistrements de requête

L’ajout de cette chaîne à la fin d’une requête GET à l’API limite le nombre d’enregistrements récupérés :

?start_element=N&num_elements=N

Exemples

segment/1?start_element=0&num_elements=1000
member?start_element=0&num_elements=100
creative/1?start_element=0&num_elements=200

• Le premier élément est l’élément 0.
• Toutes les réponses GET auront une propriété « count » indiquant le nombre total d’éléments correspondant à cette requête GET.
• Cela s’applique également aux services qui ne sont pas des services de création de rapports, tels que le service de recherche créative, qui sont demandés avec des méthodes autres que les GET.

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 créatif uniquement les créatifs avec les ID 1, 2 et 3.

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

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.

Exemple : Demander toutes les créations pour certains membres

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?member_id=123,987' 

Filtrer par Min valeurs et Max

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

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_id=47'
$ curl -b cookies -c cookies 'https://api.adnxs.com/creative?min_brand_id=20'

Les champs du type date peuvent être filtrés à l’aide du min_last_modified filtre . Notez la syntaxe de date/heure requise : AAAA-MM-JJ+HH :MM :SS

$ curl -b cookies 'https://api.adnxs.com/creative/114?min_last_activity=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.adnxs.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 d’erreur 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 -c cookies 'https://api.adnxs.com/creative?like_[fieldName]=partialValue'

Valeurs de champ JSON

POST les requêtes et PUT nécessitent des données au format JSON. POST demande généralement créer des objets dans la base de données, et donc exiger toutes les informations sur cet objet (sauf s’il est modifié par la suite par une requête PUT). 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.

Authentification

Avant de pouvoir utiliser les API, vous devez vous authentifier avec votre nom d’utilisateur et votre mot de passe. Pour plus d’informations, consultez Service d’authentification .

Codes de réponse

Tous les services d’API retournent des données au format 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 POST et PUT inclut également l’ID de l’objet approprié, tel que soumissionnaire, membre, balise ou créatif, ainsi que tous les attributs pertinents de cet objet. (Dans l’exemple ci-dessous, nous utilisons des cookies pour stocker notre jeton d’authentification et ajouter le fichier « tag » au service tiny tag.)

$ curl -b cookies -c cookies -X POST --data-binary @tag https://api.adnxs.com/tt/32/
{
    "response": {
        "status": "OK",
        "id": "242"
    }
}

Erreurs

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" . Pour certaines conditions d’erreur, vous pouvez également voir les champs facultatifs "error_description" et "error_code" .

$ curl -b cookies -c cookies 'https://api.adnxs.com/api/auth?username=admin&password=Wr0ngP@ss'
{
    "response": {
        "error": "No match found for user\/pass",
        "error_id": "NOAUTH"
    }
}

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 suit :

Rubrique connexe

Services d’API du soumissionnaire