Una buena API se siente aburrida en el mejor sentido: URLs predecibles, errores honestos, esquemas pequeños y estables, sin sorpresas. Estos son los principios que dan forma a la API de servidor de Noxyr, tomados de los estándares de la industria detrás de Stripe, Resend, OpenAI y la API oficial de Discord.
1. URLs versionadas
Cada endpoint vive bajo /api/v1/. Cuando añadamos cambios que rompan la compatibilidad, llegarán bajo /api/v2/: las integraciones antiguas seguirán funcionando. Discord hace lo mismo con /api/v10/. Si tu API no tiene versiones, cada cambio de esquema se convertirá en un ticket de soporte.
2. Primero los recursos, después las acciones
Los endpoints de Noxyr se nombran con sustantivos: server, tickets, activity, invoices, reviews, giveaways. Todos son de solo lectura, todos GET. Cuando añadamos escrituras, serán POST/PATCH/DELETE sobre los mismos recursos. Esto encaja bien con las convenciones de REST y mantiene el modelo mental muy simple.
3. Tokens Bearer, un solo secreto
La autenticación es Authorization: Bearer nxr_.... Sin peticiones firmadas, sin flujo OAuth para los datos de servidor de solo lectura. Las APIs modernas para desarrolladores convergen en esto porque funciona en todas partes: curl, navegadores, Postman, edge serverless. Discord también usa tokens bearer para los usuarios autorizados mediante OAuth; el patrón es universal.
4. Guardar solo hashes
Cada clave de Noxyr se guarda con SHA-256 en el servidor. El valor original se muestra una sola vez, al generarla, y nunca más. Si nuestra base de datos se filtrara, ninguna clave sería utilizable. Stripe, GitHub, Resend y cualquier otro proveedor de API bien gestionado hace lo mismo: guardar las claves de forma reversible es una señal de alarma.
5. Permisos detallados
Una clave, seis interruptores independientes. Las reseñas son datos públicos; las ventas son privadas. Separarlos significa que puedes compartir una clave solo para reseñas con un socio de marketing y mantener las cifras de ingresos detrás de otro interruptor. Los cambios de permisos surten efecto al instante (se comprueban en cada petición), así que revocar no requiere rotar la clave.
6. Respuestas de error honestas
Cada error es JSON con un código estable legible por máquinas y un mensaje legible por personas:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }Los códigos legibles por máquinas facilitan los reintentos y los paneles. Los mensajes legibles por personas hacen más rápida la depuración. Las búsquedas de "discord increased api errors" en julio de 2026 (la tendencia "breakout" en Google Trends) muestran lo que pasa cuando los errores son opacos: los usuarios adivinan.
7. Series temporales con relleno de ceros
El endpoint /api/v1/activity devuelve cada día del rango solicitado, incluso cuando el recuento es cero. Los frontends no tienen que rellenar huecos; los gráficos no saltan entre fechas dispersas. Es un pequeño detalle con un gran beneficio para la calidad de uso.
8. Límites de tasa con cabeceras
Cada respuesta incluye cabeceras RateLimit-* para que los clientes puedan reducir la frecuencia antes de llegar a un 429. Es el formato estandarizado del borrador IETF, con la misma forma que GitHub y otras APIs modernas, así que cualquier biblioteca cliente que lo soporte funciona sin cambios.
9. CORS permisivo para datos de solo lectura
Los endpoints de solo lectura envían Access-Control-Allow-Origin: *. Como lo que autentica es la clave y no el origen, abrir CORS no cuesta nada en seguridad y permite que las herramientas del navegador llamen a la API directamente, sin proxy ni soluciones con localhost.
10. Esquemas pequeños y estables
Cada respuesta cabe en una pantalla. Sin objetos anidados opcionales, sin campos que aparecen solo cuando una función está activada. Los esquemas pequeños se pueden cachear, probar y tipar fácilmente en TypeScript.
Mira un ejemplo práctico: Tutorial de la API de servidor. Y cuando el propio Discord da problemas, qué significan realmente esos errores de la API de Discord.