Especificación Técnica Pública

NodeContract

Especificación técnica abierta para la integración soberana y descentralizada de nodos externos en Portal Sur.

/docs/node-contract

Principios del Contrato

El nodo es soberano. Portal Sur nunca escribe en el nodo.

Solo lectura. Todos los endpoints son estrictamente de método GET.

Datos públicos. Solo datos agregados. Nunca información personal.

Sin autenticación. Cualquiera puede consultar un nodo público libremente.

Agnóstico al stack. Cero dependencias; adaptable a cualquier lenguaje o hosting.

Endpoints Mínimos

GET /info

Devuelve los metadatos públicos principales del nodo.

{
"slug": "unos-mates",
"name": "Unos Mates en lo de Nelson",
"type": "music",
"description": "Música, conducción y producción.",
"url": "https://unosmatesenlodenelson.com.ar",
"contact": "contacto@unosmates.com.ar",
"since": "2024"
}
Campos obligatorios: slug, name, type, url.
Tipos válidos: music, education, radio, huerta, coop, other.
GET /health

Verifica la disponibilidad y estado operacional del nodo.

{
"status": "ok",
"version": "1.0.0"
}
Uso: Portal Sur realiza un ping cada 24hs. Si el nodo no responde, se marca visualmente como inactivo (sin ser eliminado).
GET /resources Opcional

Lista los recursos públicos expuestos directamente por el nodo.

{
"resources": [
{
    "id": "cancion-1",
    "type": "cancion",
    "title": "Caminando",
    "url": "https://unosmates.com.ar/cancion/caminando",
    "thumbnail": "https://unosmates.com.ar/img/caminando.jpg",
    "published_at": "2025-03-14",
    "meta": {}
}
]
}
Uso: Permite construir un feed agregado global. Portal Sur no almacena los recursos; los consulta en tiempo real.

Eventos y Notificaciones

POST /notify Opcional

Permite al nodo notificar proactivamente a Portal Sur sobre la publicación de nuevos contenidos para acelerar su indexación.

Contrato de Respuesta y Errores

• Todos los endpoints deben responder con la cabecera Content-Type: application/json.
• Las respuestas de error deben mantener el siguiente formato estándar indicando el código HTTP correspondiente: 

{
"error": true,
"message": "Descripción detallada del problema"
}

Códigos HTTP esperados: 200 (OK), 404 (No existe), 500 (Error interno).

Lo que Portal Sur NUNCA solicita

Cómo sumarse a la red

1
El nodo implementa localmente los endpoints GET /info y GET /health.
2
El equipo de Portal Sur verifica manualmente el cumplimiento del código de conducta.
3
Se registra la URL pública del nodo dentro del directorio central.
4
Portal Sur comienza la verificación y consulta periódica del nodo.
Integración Curada: El alta no es automatizada. Todo nodo se incorpora previa revisión humana para preservar la calidad del directorio.