Visión general
Lee y escribe en una cuenta de uloggd desde tu propio código, con una llave que nunca puede más que su dueño.
Una llave resuelve a la cuenta que la creó, y cada petición corre como esa cuenta. Las reglas que deciden lo que el sitio puede hacer deciden lo que la llave puede hacer, porque son las mismas reglas: viven en la base de datos, no en los handlers.
El diseño entero cabe en una frase. Una llave nunca puede hacer algo que su dueño no podría.
Crear una llave
Toda llave pertenece a una aplicación. En el portal de desarrolladores, crea una aplicación, marca en Permisos lo que necesita y, en Llaves, crea la llave. El token aparece una vez y se guarda solo como hash, así que si lo pierdes creas otro en lugar de recuperarlo.
Prefiere una expiración a nunca. Una llave que expira es una llave que deja de importar cuando te olvidas de ella.
Tu primera petición
curl https://uloggd.com/api/v1/me \
-H "Authorization: Bearer ulg_live_..."/api/v1/me no exige permiso, así que responde a cualquier llave viva y te dice
qué está sosteniendo:
{
"key": { "id": "...", "scopes": ["catalog.read", "library.read"] },
"owner": { "id": "...", "username": "ada", "display_name": "Ada" }
}Leer a otras personas
Tu clave lee cualquier perfil por nombre, no solo el tuyo. Todo lo que está en
/api/v1/profiles/{username}/… acepta el nombre de otra persona: perfil,
resumen, biblioteca, estadísticas, reseñas, listas, capturas, recorridos y el
año.
curl "https://uloggd.com/api/v1/profiles/ada/library?playing=true&games=1" \
-H "Authorization: Bearer ulg_live_..."La respuesta es lo que esa persona te muestra a ti, el dueño de la clave: todo en una biblioteca pública, nada en una privada, y una solo para seguidores solo si la sigues. Nadie necesita crear una clave para ser consultado, y un bot que muestra la biblioteca de quien la pidió solo necesita su nombre.
La forma de una respuesta
Una colección responde { data, page }. Un recurso único responde { data }.
Toda falla responde { error }, incluso en el 500. Nada más.
Los cambios aditivos entran en la v1; lo que quita un campo o cambia lo que significa espera a la v2 (consulta Versionado).
Arcade
Para llevar un juego web que alojas tú a los jugadores de uloggd, lee las guías de Arcade. Las rutas de desarrollador y de jugador de Arcade son solo para sesión, así que ninguna llave las alcanza en esta fase; su directorio, sus páginas de la tienda y sus llaves de identidad son públicos.