Paginación y filtrado de limitación

Limitación

Para evitar el abuso de los servicios de API, se aplica un límite de velocidad para cada servicio. El límite de velocidad específico dependerá del punto de conexión al que llame un usuario. Este enfoque difiere de la limitación de velocidad anterior, que se centró en los límites de cliente. Estos límites se ajustan con el tiempo, por lo que no se proporcionan detalles específicos. Sin embargo, la respuesta limitada por velocidad proporcionará la información necesaria para ajustar las llamadas o scripts en consecuencia.

Si supera el límite de limitación, la API responderá con http 429 (demasiadas solicitudes, lo que indica que el usuario ha realizado demasiadas llamadas a este servicio) o el código de respuesta HTTP 503 (Servicio no disponible), lo que significa que el servicio está saturado de solicitudes y no puede tomar más código de respuesta. También proporcionará encabezados pertinentes para ayudarle a comprender por qué ocurrió esto y qué hacer a continuación.

Encabezados de límite de velocidad

Cuando recibe un error 429, indica que la solicitud tenía una velocidad limitada. Para obtener una respuesta 503, deberá comprobar los encabezados para confirmar si se debe a la limitación de velocidad. Busque el primer encabezado enumerado a continuación, que indica que el 503 fue causado por la limitación de velocidad.

1. x-ratelimit-code: corresponde al código HTTP devuelto cuando la llamada era de velocidad limitada.
   1. Un 429 indica que el usuario ha superado el límite por usuario establecido por el servicio.
   2. Un 503 indica que el servicio está aplicando un límite de velocidad basado en el total de llamadas en ese momento.
   3. Para ambos códigos, se incluye un encabezado "retry-after" para especificar cuándo volver a intentar la solicitud.
2. retry-after: muestra el tiempo en segundos que se debe esperar antes de volver a intentar la solicitud.
3. x-ratelimit-count: muestra el número total de llamadas que el usuario ha realizado dentro del período límite. Los usuarios pueden usar esta información para ajustar los patrones de llamada cuando se encuentran con solicitudes de velocidad limitada.
   1. Este encabezado solo se incluye si el código de estado es 429.

Paginación

La API limita las respuestas a cualquier solicitud a 100 objetos. La paginación le permitirá usar varias solicitudes para recuperar más de 100 objetos en total, aunque cada solicitud única todavía está limitada a 100 objetos. Esto se logra mediante los start_element parámetros y num_elements querystring. En el ejemplo siguiente, usamos varias llamadas HTTP GET para recuperar muchas creatividades.

Nota:

La salida se ha abreviado para ahorrar espacio.

Paginación: ejemplo

$ curl -c cookies -b cookies 'https://api.appnexus.com/creative?start_element=0&num_elements=100'
{
  "response": {
    "status": "OK",
    "creatives": [...],
    "count": 203151,
    "start_element": 0,
    "num_elements": 100
  }
}
$ curl -c cookies -b cookies 'https://api.appnexus.com/creative?start_element=100&num_elements=100'
{
  "response": {
    "status": "OK",
    "creatives": [...],
    "count": 203151,
    "start_element": 100,
    "num_elements": 100
  }
}
$ curl -c cookies -b cookies 'https://api.appnexus.com/creative?start_element=200&num_elements=100'
{
  "response": {
    "status": "OK",
    "creatives": [...],
    "count": 203151,
    "start_element": 200,
    "num_elements": 100
  }
}

Filtrado

El filtrado permite especificar un subconjunto de objetos que va a devolver la API. El filtro más común y posiblemente más útil es min_last_modified, que solo devuelve objetos que se han cambiado desde la fecha especificada. En el ejemplo siguiente, usamos el filtrado en una solicitud de API GET para devolver solo las creatividades modificadas después del 14/05/2013 00:00:00 UTC.

Nota:

La salida de la llamada API se ha abreviado para ahorrar espacio.

Filtrado: ejemplo

$ curl -b cookies -c cookies 'https://api.appnexus.com/creative?min_last_modified=2013-05-14+00:00:00'
{
  "response": {
    "status": "OK",
    "creatives": [
      {
        "id": 298390,
        "last_modified": "2011-07-13 16:08:32",
        ...
      },
      {
        "id": 298391,
        "last_modified": "2011-07-13 16:08:32",
        ...
      },
      {
        "id": 317677,
        "last_modified": "2011-07-13 04:44:04",
        ...
      },
      {
        "id": 317678,
        "last_modified": "2011-07-13 04:12:57",
        ...
      },
      {
        "id": 328516,
        "last_modified": "2011-07-13 18:18:21",
        ...
      },
      {
        "id": 328531,
        "last_modified": "2011-07-13 18:57:12",
        ...
      }
    ],
    "count": 1740,
    "start_element": 0,
    "num_elements": 6
  }
}