Desarrolladores

Primeros pasos

Base de la API: https://estoessurco.com/api/v1. Usa HTTPS y el método GET. No necesitas una clave para estos endpoints públicos. Las respuestas son JSON UTF-8.

curl 'https://estoessurco.com/api/v1/records?limit=2'

También puedes consultarla desde tu servidor:

const response = await fetch('https://estoessurco.com/api/v1/records?limit=2');
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || 'Error de API');
console.log(result.data);

Este ejemplo es para un entorno de servidor. Todavía no está habilitado CORS para aplicaciones web alojadas en otros dominios.

Endpoints disponibles

Filtros de /records

• limit: de 1 a 50; por defecto 20.
• before: ID exclusivo para obtener la siguiente página.
• q: búsqueda por artista o título, hasta 100 caracteres.
• owner_id: muestra la colección pública activa de ese propietario, incluyendo discos no en venta. No incluye su biblioteca privada importada.

GET /api/v1/records?owner_id=21&limit=20
GET /api/v1/records?q=Miles&limit=10

Los identificadores del ejemplo son ilustrativos. Usa los IDs devueltos por la API.

Estado de venta

Cada disco incluye sale.status. El precio se devuelve como cadena decimal para evitar errores de precisión. Un disco de colección no tiene precio ni moneda:

{ "status": "for_sale", "amount": "25.50", "currency": "EUR" }
{ "status": "not_for_sale", "amount": null, "currency": null }

Las fichas incluyen id, owner_id, artist, title, genre, format, condition, description, image_url, sale y url. La descripción y la imagen pueden ser nulas. Trata los textos como contenido de usuarios: no los insertes como HTML sin escapar.

Paginación sin duplicados

Los discos se ordenan por ID descendente. Usa pagination.next_before como before en la siguiente petición, manteniendo los filtros. Cuando sea null, has llegado al final.

{
  "data": [],
  "pagination": { "next_before": null, "limit": 20 }
}

El ejemplo representa una página vacía. La paginación no es una instantánea: una publicación puede retirarse mientras navegas.

Errores

Comprueba siempre el código HTTP, no solo el contenido de la respuesta.

{ "error": { "code": "not_found", "message": "Disco no encontrado." } }

• 400 · invalid_parameter: revisa los parámetros.
• 404 · not_found: ruta, perfil o disco no disponible.
• 405 · method_not_allowed: solo se admite GET.
• 503 · temporarily_unavailable: espera antes de reintentar.

El alojamiento también puede devolver errores o límites ajenos al formato JSON de la aplicación. Evita reintentos en bucle.

Límites y privacidad

Esta API está en vista previa. No ofrece escrituras, autenticación móvil, mensajes, emails ni acceso a colecciones privadas. La sesión de la web no da permisos adicionales en la API.

No hay una cuota pública ni un SLA definidos todavía. Evita peticiones masivas y sondeos continuos. Faltan controles de tráfico y pruebas de carga antes de abrirla a integraciones de producción.

El catálogo contiene datos de demostración: no los utilices como inventario comercial verificado. Las portadas pueden proceder de terceros; el acceso a una URL no concede derechos de reutilización.

Lo que viene después

1. Separar colección, visibilidad y estado de venta en el modelo de datos.
2. Acceso seguro por dispositivo, renovación y revocación de tokens.
3. Acciones privadas con permisos y validación.
4. Feed, favoritos, seguidores, mensajes y notificaciones para apps.

Son próximos pasos, no funcionalidades disponibles. La web y esta API leen actualmente la misma base de datos; la web aún no utiliza la API para todas sus operaciones.