Procedimientos recomendados de API

Estamos encantados de que aproveche nuestra plataforma mediante la captura de datos sin procesar, el enganche en sus propias piezas del rompecabezas que sirve anuncios o, de lo contrario, se basa en nuestra infraestructura. Siga los procedimientos recomendados para asegurarse de que tiene la mejor experiencia posible y para mantener las aplicaciones en buen estado a medida que evoluciona nuestra API. Manténgase en contacto con su consultor de implementación a medida que empiece a compilar.

Filtrar los resultados

El filtrado permite especificar un subconjunto de objetos que se van a devolver. Por ejemplo, la siguiente llamada devolvería solo creatividades activas:

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

Para los campos del tipo int, double, date o money, puede anexar min_ o max_ al filtro. Por ejemplo, la siguiente solicitud devolvería solo las campañas que se han modificado el 1 de enero de 2013 o después:

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

Nota:

Para cada servicio, puede averiguar qué campos se pueden filtrar y ordenar anexando /meta a la dirección URL del servicio. Para obtener más información, consulte Semántica de API.

Paginar los resultados

Aunque ahora solo tenga cinco creatividades en el sistema, debe escribir la aplicación de forma que aproveche la compatibilidad con la paginación, ya que es probable que este número aumente en el futuro. Puede paginar los resultados especificando start_element y num_elements en la cadena de consulta de la solicitud GET. Por ejemplo, la siguiente solicitud devolvería los primeros 50 objetos de la respuesta:

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

Para recuperar los 50 siguientes, simplemente establecería start_element=50.

Nota:

El número máximo de objetos que se pueden devolver, independientemente de la paginación, es 100. Tenga en cuenta que si solicita más de 100 objetos, solo devolveremos los primeros 100 y no proporcionaremos un mensaje de error. Para obtener más información, consulte la página Semántica de API .

Limitación de las llamadas

Hay límites en el número de solicitudes que puede realizar en nuestras API por minuto. Clasificamos estos límites en límites de velocidad de lectura y escritura. Actualmente, el límite predeterminado de lectura y escritura es 1000 por minuto. Estos contadores se restablecerán al final del minuto, pero si supera el límite de limitación, la API responderá con el código de respuesta HTTP 429 (demasiadas solicitudes). Vuelva a intentar la solicitud en el número de segundos especificado en el Retry-After campo del encabezado.

También hay un límite de solicitudes simultáneas de 20 solicitudes a la vez. Más de este límite devolverá un HTTP 200, pero con una carga de error.

A continuación se muestra un ejemplo de los valores de encabezado en respuesta a una solicitud que superó el límite de velocidad de un miembro.

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

Pasar valores de campo en lugar de depender de valores predeterminados

Se recomienda pasar los valores de campo que desee en lugar de depender de los valores predeterminados. Si cambian los valores predeterminados y se basa en valores predeterminados, puede experimentar resultados inesperados.

Evitar actualizaciones innecesarias

Al actualizar objetos, no pase campos que no cambien. Una buena manera de evitar esto es almacenar en caché las llamadas GET, comparar la memoria caché con los cambios que desea realizar y, a continuación, realizar llamadas PUT solo para lo que es diferente.

Evitar la autenticación innecesaria

Puede autenticarse correctamente 10 veces en un período de 5 minutos. Los intentos de autenticación posteriores en esos 5 minutos producirán un error.

Nota:

Cuando se autentica, recibe un token de autorización que permanece activo durante 2 horas. Se recomienda volver a autenticarse solo después de recibir el "NOAUTH" error_id en las respuestas de llamada. Si sigue esta práctica, la restricción anterior no debería tener ningún impacto en la implementación.

Para obtener instrucciones de autenticación, consulte Servicio de autenticación.

Uso de un punto final de API controlada por la configuración

Asegúrese de que puede cambiar fácilmente la dirección URL base de la API. En el ejemplo siguiente, la dirección URL de la API se define como una variable y se puede usar en toda la base de código. Si esa dirección URL debe cambiar alguna vez, se puede modificar en una sola ubicación.

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

Compilación de un contenedor de API

Centralizar el código en el que se envían solicitudes y se controlan las respuestas es una práctica excelente. Esto le permitirá realizar el registro, el control de errores y mucho más en una ubicación.

No extraer todos los informes al mismo tiempo

Esto puede hacer que el back-end de informes se sobrecargue, lo que da lugar a informes retrasados e incluso puede afectar a los informes que se ejecutan más adelante en el día.

Leer toda la wiki de API antes de usar la API

Hay muchas sugerencias, trucos y ejemplos en toda la wiki de API que serán útiles para desarrollar la integración.

Uso de códigos de integración

En lugar de almacenar identificadores Xandr, puede usar los códigos de integración para hacer referencia al objeto en la API. Estos códigos deben ser únicos entre un tipo de objeto y un miembro Xandr. En el ejemplo siguiente se usa un código de integración para identificar una campaña.

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

No suponga que una llamada API se realizó correctamente

Todas las llamadas API correctas recibirán una respuesta que contiene un "status" de "OK". Si la respuesta no contiene este estado, se produjo un error en la llamada por algún motivo. "status" Si es "error", se incluirá un mensaje de error en la respuesta. A continuación se muestra un ejemplo de una respuesta correcta.

{
   "response": {
      "status": "OK",
      "campaign": {
         ...
      }
   }
}

Permitir campos adicionales en las respuestas

A medida que nuestro equipo de API implementa nuevas características, es necesario incluir nuevos campos en varios servicios de API. La integración debe ser lo suficientemente flexible como para controlar campos adicionales en cada servicio que no se devolvieron anteriormente.

Tenga en cuenta los cambios importantes

Nuestros servicios cambian continuamente a medida que agregamos nuevas características, pero hacemos todo lo posible para crear estabilidad para que las aplicaciones que nuestros clientes basan en nuestra API puedan adaptarse correctamente también.

Al introducir un cambio importante, admitiremos dos versiones de la API en producción, una con y otra sin el cambio importante, durante 60 días. Anunciaremos estos cambios en nuestras notas de la versión de API. Para obtener más información sobre lo que constituye un cambio importante, consulte nuestra directiva de cambios importantes .

Tenga en cuenta los límites de objetos.

Xandr limita el número de objetos que cada miembro puede crear y usar en la plataforma. Este límite incluye objetos inactivos y no utilizados (por ejemplo, campañas establecidas en estado inactivo, ubicaciones que nunca han servido una impresión, etc.). Debe usar el servicio de límite de objetos para ver los límites y supervisar de forma proactiva el uso.