Portal para desarrolladores y agentes

Todo lo que esta web publica sobre mí está también disponible como JSON, como OpenAPI y como markdown. Sin claves, sin registro y con CORS abierto.

Quickstart

Tres llamadas y ya tienes el mapa completo. Comprueba que la API responde, léela desde su especificación y pide el perfil.

curl -s https://sgomez.dev/api/v1/health
curl -s https://sgomez.dev/openapi.json
curl -s https://sgomez.dev/api/v1/profile

No hay sandbox aparte ni claves de prueba, porque la API es de solo lectura y todo su contenido ya es público, así que el entorno de producción ES el entorno de pruebas. No hay nada que puedas romper con un GET. La API responde en español por defecto y acepta ?lang=en o Accept-Language: en para el inglés.

Endpoints

Método y ruta	operationId	Qué devuelve
GET /api/v1/health	getHealth	Estado del servicio y enlaces de entrada.
GET /api/v1/profile	getProfile	Identidad, rol, ubicación, contacto y disponibilidad.
GET /api/v1/about	getAbout	Biografía larga y cronología por años.
GET /api/v1/projects	listProjects	Proyectos publicados, con stack y enlace.
GET /api/v1/projects/{slug}	getProject	Un proyecto concreto por su slug.
GET /api/v1/experience	listExperience	Puestos, organizaciones y periodos.
GET /api/v1/skills	listSkills	Tecnologías por categoría, con años de uso.
GET /api/v1/certifications	listCertifications	Certificaciones con enlace al credencial.
GET /api/v1/education	listEducation	Formación reglada.
GET /api/v1/recommendations	listRecommendations	Recomendaciones escritas por colegas y clientes.
GET /api/v1/search?q=	searchContent	Búsqueda por palabras clave sobre todo lo anterior.

Las colecciones aceptan limit (1-100) y offset (0-1000). search acepta q (obligatorio) y limit (1-50). Toda respuesta correcta va envuelta en { "data": …, "meta": … }, y meta incluye count, total, self y documentation_url.

Errores

Los errores también son JSON, con el mismo sobre siempre. code es estable y se puede usar en un switch; hint dice qué hacer para arreglarlo, que es lo que a un agente le falta cuando recibe un 404 vacío.

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "No project with slug \"nope\".",
    "hint": "Known slugs: nudaui, sortlab, … List them with GET /api/v1/projects.",
    "documentation_url": "https://sgomez.dev/developers"
  }
}

400 invalid_parameter: un parámetro falta o está fuera de rango.
404 not_found: el recurso o el endpoint no existe. Cualquier ruta desconocida bajo /api responde JSON, nunca HTML.
405 method_not_allowed: la API es de solo lectura; la respuesta incluye la cabecera Allow.

Autenticación y límites

No hay autenticación ni claves de API porque no existe ningún dato privado detrás, así que una clave solo sería un trámite. Tampoco hay límite de peticiones por cliente más allá de la protección ordinaria de la CDN. A cambio, las respuestas se sirven cacheadas (Cache-Control: public, max-age=300, s-maxage=3600). Si necesitas el catálogo entero, una llamada por colección basta, y repetir la misma llamada en bucle no te dará datos más frescos.

CORS está abierto a cualquier origen (Access-Control-Allow-Origin: *) para GET, HEAD y OPTIONS, así que la API se puede llamar desde el navegador. Los datos se publican bajo licencia CC BY 4.0, así que puedes usarlos citando la fuente.

Especificación OpenAPI

La especificación es OpenAPI 3.1 y se genera desde el mismo código que sirve los endpoints, así que no puede describir una ruta que ya no existe. Cada operación tiene operationId único, summary, description, parámetros tipados y un esquema de respuesta por código, que es justo lo que necesita un cliente de function calling para convertirla en herramientas.

/openapi.json: Ubicación canónica.
/api/openapi.json: El mismo documento bajo /api.
/api/openapi.yaml: El mismo documento en YAML.

Markdown para agentes

Las páginas de contenido se sirven en markdown cuando la petición lo pide, siguiendo la convención de acceptmarkdown.com. La URL canónica no cambia y la respuesta lleva Vary: Accept, para que una CDN no le dé a un agente la variante HTML que guardó para un navegador.

curl -s -H "Accept: text/markdown" https://sgomez.dev/about

# o, si prefieres una URL explícita:
curl -s https://sgomez.dev/about.md

Funciona en /, /about, /contact, /privacy y /developers, y en sus gemelas inglesas bajo /en/…. Las rutas que ya son markdown (/llms.txt, /agents.md) se sirven tal cual. Una ruta que no existe devuelve 404 con un cuerpo markdown que dice a dónde ir, en vez de una página de error que un agente no sabe leer.

Ficheros para agentes

/llms.txt: Resumen factual del sitio, con la sección «when to use this».
/agents.md: Para qué sirve este sitio y cómo llamarlo.
/sitemap.xml: Todas las URLs publicadas.
/robots.txt: Crawlers de IA explícitamente permitidos.
/manifest.webmanifest: Manifiesto de la aplicación web.

Versionado

La versión va en la ruta (/api/v1). Dentro de v1 solo se añaden campos y endpoints, porque quitar un campo o renombrar un operationId sería un cambio incompatible y saldría en /api/v2. Los code de error forman parte del contrato y no se renombran.

Ver en markdown