API de plataforma digital: 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. Hay algunas reglas básicas que garantizarán que tiene la mejor experiencia posible y mantendrán 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.
API Dos
Recupere solo los objetos que necesita.
Obtención de varios objetos por identificador
La mayoría de los servicios admiten la recuperación de varios objetos específicos por identificador. Para ello, anexe una lista separada por comas de identificadores a la cadena de consulta. Por ejemplo, la siguiente solicitud devolvería solo los publicadores con los identificadores especificados.
$ curl -b cookies -c cookies 'https://api.appnexus.com/publisher?id=2,3,5,8,13,21'
Filtrar los resultados
El filtrado permite especificar un subconjunto de objetos que se van a devolver. Por ejemplo, la llamada siguiente devolvería solo los elementos de línea que tienen el "active" estado :
$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?state=active'
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 los elementos de línea que se han modificado el 1 de enero de 2013 o después.
$ curl -b cookies -c cookies 'https://api.appnexus.com/line-item?min_last_modified=2019-01-01+00:00:00'
Si la llamada API devuelve un error con "Error de solicitud debido al tiempo de espera o al problema de memoria", puede anexar add_mappings=false a los parámetros de consulta. Agregar este parámetro solo devolverá los objetos de API de nivel superior, pero no sus elementos secundarios anidados.
Por ejemplo,
$ curl -b cookies -c cookies "https://api.appnexus.com/publisher?id=2,3,5,8,13,21&add_mappings=false"
Paginar los resultados
Debe escribir la aplicación para aprovechar la compatibilidad con la paginación. Puede paginar los resultados especificando start_element y num_elements en la cadena de consulta de la GET solicitud. Por ejemplo, la siguiente solicitud devolvería los primeros 50 objetos de la respuesta:
$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=50'
Para recuperar los 50 siguientes, simplemente establecería start_element=50.
Sugerencia
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.
Limitación de las llamadas
Hay límites en el número de solicitudes que puede realizar en nuestras API por minuto. Si supera el límite de limitación, la API responderá con el código de respuesta HTTP 429 (demasiadas solicitudes) junto con un mensaje de error en el contenido de la respuesta. También se devuelve un encabezado de respuesta con un Retry-After campo que especifica el número de segundos que se deben esperar antes de intentar más llamadas API.
Si realiza llamadas API mediante curl, puede recuperar el encabezado de respuesta incluyendo el parámetro -v en la solicitud.
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
...
En este caso, puede volver a intentar la solicitud en 31 segundos (el valor del Retry-After campo).
Si llama a la API desde un script, debe comprobar el código de respuesta 429 al realizar las llamadas API. Si recibe este código, espere el tiempo devuelto por el Retry-After campo del encabezado de respuesta. Después de dormir durante la cantidad de tiempo especificada, el script puede continuar.
También hay un límite de solicitudes simultáneas de 15 solicitudes a la vez. Más de este límite devolverá un código HTTP 200, pero con una carga de error.
Consulte Restricciones de uso de API para obtener más información sobre los límites de velocidad.
Actualizar matrices con "append=true"
Al actualizar los valores de matriz con la API, los valores de matriz de un objeto se sobrescribirán con los valores proporcionados en la PUT solicitud. Esto es correcto si el comportamiento previsto es borrar los valores de una matriz y reemplazarlo por los datos actualizados. Sin embargo, se puede usar una marca para anexar datos a una matriz en lugar de reemplazarlos. Esto resulta especialmente útil al actualizar matrices muy largas. El parámetro append=true de consulta se puede agregar a una PUT solicitud para establecer una actualización en modo anexado.
En nuestro ejemplo, supongamos que teníamos un objeto profile simple con la siguiente country_targets matriz:
Objeto profile, antes de la actualización
// Before Append
{
"profile": {
"code": "Test Profile",
"country_targets": [
{
"country": "US",
"name": "United States"
}
]
}
}
Si se usara append=true en la PUT llamada para actualizar a este objeto, podríamos usar los siguientes datos JSON sin miedo a sobrescribir los datos existentes country_targets de nuestro perfil:
Datos de actualización de JSON
// Update Object
{
"profile": {
"country_targets": [
{
"country": "GR",
"name": "Greece"
}
]
}
}
Usaríamos el siguiente comando CURL (reemplazando por <profile_ID> el valor adecuado).
Ejemplo de CURL
$ curl -b cookie -c cookie -X PUT -s -d '@json/profile.json' "https://api.appnexus.com/profile?id=<profile_ID>&append=true"
Como resultado. nuestro objeto de perfil se actualizaría para reflejar lo siguiente:
Objeto de perfil resultante
// After Append
{
"profile": {
"code": "Test Profile",
"country_targets": [
{
"country": "US",
"name": "United States"
},
{
"country": "GR",
"name": "Greece"
}
]
}
}
Uso de un punto de conexión de API controlado 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.appnexus.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.
Mantener los informes ajustados y centrados
Estas son algunas sugerencias para evitar que los informes sean innecesariamente grandes o que tardan mucho tiempo en procesarse:
- Acortar (
report_intervales decir, de la duración a la last_48_hours) - Agregar más filtros de nivel superior (es decir, para un publicador, anunciante, artículo de línea, etc.)
- Evite combinar dimensiones pormenorizadas de compra y de venta (es decir, creativas y de colocación), ya que esto aumenta exponencialmente el número de filas. Si necesita informar sobre estas combinaciones, considere la posibilidad de usar fuentes de informes masivas o fuentes de distribución de datos de nivel de registro.
Si debe extraer informes muy grandes, use las instrucciones de Paginación de informes.
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.
Sugerencia
Cuando se admiten dos versiones de la API durante 60 días, el cambio importante se implementará en la versión más reciente.
- Para acceder a la versión actual ( sin cambios importantes), use un formato como el siguiente:
https://api.appnexus.com/https://api.appnexus.com/current/
- Para acceder a la versión más reciente (con las características de cambio importante) use un formato como:
https://api.appnexus.com/v1.16/
Tenga en cuenta los límites de objetos.
Limitamos el número de objetos que cada miembro puede crear y usar en la plataforma. Este límite incluye objetos inactivos y no utilizados (como elementos de línea establecidos en estado inactivo, ubicaciones que nunca han proporcionado 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.
Tenga en cuenta la programación de procesos.
Si es posible, programe los procesos para que no se superpongan entre sí. Si no hay ninguna necesidad empresarial de realizar operaciones masivas durante el horario comercial, intente programar estos procesos en horas fuera del pico para maximizar el uso de la API durante todo el día. Recuerde que se le asigna una cantidad determinada de llamadas DE LECTURA y ESCRITURA por minuto. Intente aprovechar las horas en las que no realiza ninguna llamada a la API para que tenga espacio para la cabeza adicional en los momentos en que lo necesite y priorice las operaciones con intervalos de tiempo.
Api no se aplica
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",
"line-item": {
...
}
}
}
No se base en campos predeterminados
Se recomienda pasar los valores de campo que desee en lugar de depender de los valores de campo predeterminados. Si cambian los valores predeterminados y se basa en valores predeterminados, puede experimentar resultados inesperados.
No realice actualizaciones innecesarias
Al actualizar objetos, puede evitar realizar actualizaciones innecesarias pasando solo los campos que cambian a la API. Una buena manera de asegurarse de que esta práctica consiste en almacenar en caché GET las llamadas, comparar la memoria caché con los cambios que desea realizar y, a continuación, realizar PUT llamadas solo para lo que es diferente.
Si necesita actualizar todos los objetos de un conjunto (por ejemplo, actualizar en cost_cpm todas las ubicaciones de un sitio), no debe iterar a través de cada uno de los objetos que realizan PUT llamadas a ciegas. En su lugar, emita una GET llamada para recuperar el estado actual de cada uno de los objetos del conjunto. Siempre que sea posible, asegúrese de usar la funcionalidad de filtrado y ordenación documentada en semántica de API para recuperar solo los objetos que necesitarán una actualización. Compare el estado actual de los objetos devueltos con el estado deseado y emita solo PUT para los objetos que realmente requieren una actualización.
No autenticarse innecesariamente
Cuando se autentica, el token permanece válido durante 2 horas. No es necesario volver a autenticarse en este momento. Si vuelve a autenticarse, . tenga en cuenta la siguiente limitación: La API le permite autenticarse correctamente 10 veces por período de 5 minutos. Los intentos de autenticación posteriores en esos 5 minutos producirán un error.
Sugerencia
Se recomienda escuchar en las "NOAUTH"error_id respuestas de llamada y volver a autenticarse solo después de recibirlo.
Para obtener instrucciones de autenticación, consulte Servicio de autenticación.
No extraiga 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. Para obtener más información, consulte la sección Limitación de informes de la página Servicio de informes.
No realizar solicitudes masivas al servicio de informes
Si la arquitectura llama a varias solicitudes del servicio de informes por hora o día, investigue informes de nivel superior con más datos para ver si puede obtener los datos que necesita con menos llamadas a la API.
Por ejemplo, si solicita informes por hora para todos los anunciantes y publicadores de la red, determine si el uso del informe de Network Analytics satisface sus necesidades. Considere la posibilidad de usarlo como alternativa a la realización de solicitudes individuales para los informes de Anunciante Analytics o Publisher Analytics , lo que garantiza una mejor coincidencia con su caso de uso.
Para obtener más información sobre todos los informes disponibles y sus campos, consulte la documentación de la API en Reporting Service.
Sugerencia
Si ve que los informes de nivel superior no satisfacen sus necesidades, considere la posibilidad de usar las fuentes de informes masivas o las fuentes de distribución de datos de nivel de registro.