Referencia de la API

Todos los endpoints están bajo https://geofeed.network/api/v1. La versión va en la ruta y ahí se queda: un cambio incompatible tendrá /api/v2 en lugar de cambiarle el significado a un campo.

Las peticiones y respuestas son JSON, salvo el endpoint del feed, que devuelve el propio geofeed como text/csv. Todos los endpoints requieren token; ninguno es público.

GET /api/v1/prefixes

Lee tus ASN y todos sus prefijos.

PUT /api/v1/prefixes

Reemplaza los prefijos de un ASN. Requiere token con escritura.

GET /api/v1/feed

El geofeed generado, en bytes.

Crea un token en el panel, en Ajustes. Se muestra una única vez, al crearlo, y aquí solo se guarda su hash SHA-256: si lo pierdes, genera otro. Los tokens empiezan por gfn_ para que uno filtrado se reconozca en un log o en un repositorio.

Se envía como token bearer:

$ curl -sH 'Authorization: Bearer gfn_...' https://geofeed.network/api/v1/prefixes

La escritura viene desactivada y se concede por token. Un token creado sin ella puede leer todo y no cambiar nada, que es lo que debería tener un script de monitorización. Revocar un token surte efecto en la siguiente petición; no hay caché que esperar.

El límite es de 120 peticiones por minuto y token. Por encima, devuelve 429 con rate_limited.

Devuelve el identificador de tu feed, tus ASN con su recuento y todos los prefijos. Añade ?asn=64512 para limitarlo a un ASN.

$ curl -sH 'Authorization: Bearer gfn_...' 'https://geofeed.network/api/v1/prefixes?asn=64512'

{
  "geofeed_id": "a1b2c3d4e5f6",
  "asns": [
    { "asn": 64512, "description": "Example Net", "prefixes": 2 }
  ],
  "prefixes": [
    {
      "network": "192.0.2.0/24",
      "asn": 64512,
      "country": "ES",
      "region": "Madrid",
      "region_code": "ES-M",
      "city": "Madrid",
      "postal": "28001",
      "published": true
    },
    {
      "network": "203.0.113.0/24",
      "asn": 64512,
      "country": null,
      "region": null,
      "region_code": null,
      "city": null,
      "postal": null,
      "published": false
    }
  ]
}

El campo al que hay que mirar es published. Un prefijo sin país no se escribe en el geofeed —publicar una ubicación sin país sería publicar una suposición—, así que se queda en tu cuenta, invisible para los consumidores, hasta que le des uno. published: false es la única señal de que un prefijo que añadiste no se está sirviendo.

Reemplaza los prefijos de un ASN. Un reemplazo y no un parcheo, porque es lo que una fuente de verdad quiere decir: *estos son los prefijos ahora*. Todo lo que esté en ese ASN y no venga en la petición se borra; los demás ASN no se tocan.

Se aceptan dos formas. Un array, si lo genera un IPAM:

$ curl -X PUT https://geofeed.network/api/v1/prefixes \
    -H 'Authorization: Bearer gfn_...' \
    -H 'Content-Type: application/json' \
    -d '{"asn": 64512, "prefixes": [
          {"network": "192.0.2.0/24", "country": "ES", "region": "ES-M", "city": "Madrid", "postal": "28001"},
          {"network": "2001:db8::/32", "country": "ES"}
        ]}'

O un geofeed como texto, que es lo que ya tienes si publicas uno en otro sitio. Aquí se aceptan nombres de región y se resuelven a códigos ISO 3166-2, porque es lo que contienen los feeds que ya existen:

$ curl -X PUT https://geofeed.network/api/v1/prefixes \
    -H 'Authorization: Bearer gfn_...' \
    -H 'Content-Type: application/json' \
    -d '{"asn": 64512, "geofeed": "192.0.2.0/24,ES,ES-M,Madrid,28001\n2001:db8::/32,ES,,,"}'

La respuesta es el recuento de lo que cambió, para que un pipeline pueda comprobarlo:

{
  "asn": 64512,
  "added": 2,
  "updated": 0,
  "deleted": 1,
  "skipped": 0,
  "unresolved_regions": 0
}

skipped cuenta las filas que no se pudieron interpretar o cuyo país no es un código ISO 3166-1 alfa-2 real. unresolved_regions cuenta los nombres de región sin equivalencia ISO 3166-2: esos se guardan como nombre y se publican igual, pero no son lo que pide el RFC 8805.

Límites: 5.000 prefijos por petición, y el ASN tiene que existir ya en tu cuenta. Añádelo antes en el panel.

Los bytes exactos que sirve tu feed publicado, generados al momento. Útil en un pipeline que quiera comparar lo que está a punto de publicarse, y funciona antes de haber publicado nada.

$ curl -sD- -o feed.csv -H 'Authorization: Bearer gfn_...' https://geofeed.network/api/v1/feed
x-geofeed-lines: 2
x-geofeed-skipped: 1

X-Geofeed-Lines es lo que se escribió; X-Geofeed-Skipped, cuántos prefijos quedaron fuera por no tener país. Un recuento de descartes distinto de cero merece hacer fallar el pipeline.

Añade ?asn=64512 para el feed de un solo ASN. La columna de región sigue el ajuste de formato de tu cuenta, igual que el archivo publicado.

Todos los errores son JSON con un código en error y a veces un detail. Los códigos son estables; el texto del detalle no, así que compara por el código.

401 missing_token

Falta la cabecera Authorization, o no era un token bearer.

401 invalid_token

El token no existe o ha sido revocado.

403 read_only_token

El token se creó sin permiso de escritura.

404 unknown_asn

Ese ASN no está en tu cuenta.

400 invalid_json

El cuerpo no era JSON.

400 missing_asn

No hay un asn utilizable en la petición.

400 missing_payload

No se envió ni prefixes ni geofeed.

400 too_many_prefixes

Más de 5.000 en una sola petición.

429 rate_limited

Más de 120 peticiones en un minuto para ese token.

Tu geofeed se sirve, sin autenticación, en https://geofeed.network/geofeeds/<tu-id>.csv, y por ASN en https://geofeed.network/geofeeds/<tu-id>-asn<ASN>.csv. Esa es la URL que pones en tu objeto del registro, y es la única parte de este servicio con la que hablan terceros.

Lleva un ETag fuerte sobre los bytes exactos y Cache-Control: public, max-age=3600, así que un consumidor que se porte bien revalida en lugar de volver a descargar. Una petición condicional que coincide devuelve 304, y un 304 es una lectura correcta: el consumidor ya tiene tus datos.

Un fallo de base de datos devuelve 503, nunca 404. Un 404 le dice al consumidor que no tienes geofeed, y algunos lo cachean. Un 503 le dice que vuelva.

Hay un feed de ejemplo permanente que puedes descargar sin cuenta, generado por el mismo código que los reales:

$ curl -s https://geofeed.network/geofeeds/example.csv
# network,country,region,city,postal_code
192.0.2.0/24,ES,ES-M,Madrid,28001
198.51.100.0/24,US,US-NY,New York,10001
203.0.113.0/24,DE,,,
2001:db8::/32,ES,ES-B,Barcelona,08001
2001:db8:1::/48,JP,JP-13,Tokyo,100-0001

El RFC 8805 define un geofeed como un CSV de cinco columnas —network,country,region,city,postal_code—, un prefijo por línea y # para comentarios. Solo el prefijo y el país son significativos; las otras tres son opcionales y un consumidor que no pueda usarlas las ignora.

El país es un código ISO 3166-1 alfa-2. La región es un código de subdivisión ISO 3166-2 (ES-M), no un nombre de región: es el campo que más feeds publicados tienen mal, y recortar el nombre a dos letras produce códigos que no existen.

Un feed solo con país es válido, útil y es lo que son la mayoría de los feeds publicados. Empieza por ahí.

No por nosotros. El RFC 9092 dice que un consumidor lee el atributo geofeed: del objeto inetnum o inet6num que cubre el prefijo, o una línea remarks: Geofeed <url> donde el registro no tenga atributo propio.

inetnum:        192.0.2.0 - 192.0.2.255
netname:        EXAMPLE-NET
country:        ES
geofeed:        https://geofeed.network/geofeeds/example.csv

Ponerlo en el aut-num es el error más común. Algunos consumidores miran ahí; la mayoría no. El panel puede consultar RDAP y decirte si el objeto del registro que cubre cada prefijo referencia de verdad tu feed, referencia otra URL o no referencia nada.