Cómo construí una API pública para mi sitio personal y los agentes de IA

Añadí una API pública v1 a mi sitio personal porque quería que también lo pudieran leer otras herramientas además del navegador.

HTML funciona bien para las personas. JSON resulta más útil para las herramientas.

Si un agente de IA, un buscador, una herramienta de reclutamiento o un script quiere entender mi trabajo, debería poder consultar contexto estructurado directamente. No tendría que extraer texto de la interfaz, adivinar qué secciones importan ni deducir datos del diseño.

La restricción de diseño

Esta API expone contexto público del sitio. No es la API de una plataforma SaaS.

Eso cambia las prioridades:

• claridad antes que ingenio;
• campos estables antes que flexibilidad máxima;
• resúmenes antes que volcados de datos sin contexto;
• acceso sencillo antes que autenticación compleja;
• límites de peticiones y atribución antes que barreras de acceso.

La API facilita consumir el contenido público del sitio. No expone lógica de negocio privada.

El formato de respuesta

Todos los endpoints de contenido público devuelven una estructura coherente.

Las respuestas de colecciones incluyen:

{
  "api_version": "1.0.0",
  "ai_summary": "Found 3 products. Statuses: active, in_development.",
  "meta": {
    "total": 3,
    "returned": 3,
    "locale": "en",
    "generated_at": "2026-06-05T00:00:00.000Z"
  },
  "data": []
}

Las respuestas de un solo elemento siguen la misma idea, pero devuelven un objeto en data.

Ese formato les da a los clientes varias garantías:

• api_version permite identificar cambios;
• ai_summary ofrece una interpretación legible para los agentes;
• meta explica cuándo y cómo se generó la respuesta;
• data conserva una estructura limpia y previsible.

Por qué incluir ai_summary

La mayoría de las API se construyen para clientes que ya saben lo que quieren: un script, una aplicación o un panel.

Una API pensada para agentes tiene un segundo consumidor: el modelo.

El modelo puede leer el JSON directamente, pero el JSON no siempre explica la intención. Un resumen breve le ayuda a entender qué devolvió el endpoint y cómo usarlo.

Por ejemplo, la respuesta de proyectos puede decir:

Found 4 project(s) tagged "ai". Returning 4. Technologies featured: TypeScript, Python, Next.js.
Each project includes a why_it_matters field that explains the motivation behind it.

El resumen indica que se encontraron cuatro proyectos con la etiqueta ai, enumera las tecnologías y explica que why_it_matters contiene la motivación de cada proyecto.

Así el agente sabe qué incluye la respuesta, qué filtros se aplicaron y qué campos merecen atención.

El mapa de endpoints

La API expone:

GET /api/v1/me
GET /api/v1/projects
GET /api/v1/projects/:slug
GET /api/v1/products
GET /api/v1/products/:slug
GET /api/v1/notes
GET /api/v1/notes/:slug
POST /api/v1/newsletter/subscribe
POST /api/v1/inquiries
POST /api/products/feedback

Los endpoints de lectura están diseñados para consultar contenido público.

Los de escritura cubren operaciones del producto: suscripciones al boletín, consultas y comentarios sobre productos. Los comentarios viven fuera de la API pública de consulta v1 porque esos registros son datos operativos, no contexto del portafolio.

Filtros pensados para consultas reales

Los filtros útiles son deliberadamente sencillos:

• locale para contenido público localizado;
• tag para proyectos y productos;
• status para trabajo activo o archivado;
• featured=true para productos destacados;
• topic y category para notas;
• limit y offset para paginar.

Son los filtros que espero que utilicen los consumidores reales.

Alguien podría pedir:

• «Muéstrame los proyectos activos de IA».
• «Encuentra notas sobre extensiones de Chrome».
• «Enumera los productos destacados».
• «Resume el trabajo de Orlando en español».

La estructura de la API responde a esos casos.

Límites de peticiones y confianza

La API usa un límite sencillo y gratuito para las lecturas públicas: 60 peticiones por minuto y por IP.

Los envíos de comentarios y consultas tienen límites más estrictos.

Esos límites ayudan a mantener la API estable para todos. Las cabeceras informan de las reglas sin obligar al cliente a adivinarlas.

Lo que aprendí al diseñar para agentes

Diseñar una API que los agentes puedan leer consiste, en gran parte, en aplicar el diseño habitual de API pensando un poco más en quien la consume.

Sigues necesitando:

• esquemas estables;
• validación;
• paginación;
• CORS;
• errores claros;
• límites de peticiones.

También conviene preguntarse:

• ¿Dónde podría confundirse una IA o perder el sentido de la respuesta?
• ¿Qué campos explican por qué importa este trabajo?
• ¿Puede la respuesta resumir su propio contenido?
• ¿Puede una herramienta usar esto sin extraer datos de una página renderizada?

La última pregunta es la que más me interesa. Creo que vamos hacia páginas para las personas y datos estructurados para las demás herramientas. Al menos, esa es la apuesta que estoy haciendo con mi sitio.