API de Datos¶

Errores y Validación¶

Existen varios tipos de errores que pueden devolverse desde la API de datos:

Errores de Validación (400): la petición al servidor es inválida porque se le ha pasado uno o más parámetros inválidos, o su estructura no es la esperada.
Errores de Autenticación (401): un token ha sido usado de forma inválida:
Error interno (500-599): una excepción inesperada y que ha causado una terminación del servidor. No tendrá ningún mensaje que lo acompañe.

Errores de Validación¶

Todos los endpoints validan los parámetros que se le pasan. Generalmente, se comprueba lo siguiente:

Que su valor no sea nulo.
Que el tipo sea el adecuado. Esto será importante solo cuando la variable sea algo distinto a una cadena.
Comprobaciones lógicas

Casos específicos¶

El correo electrónico tiene que cumplir la siguiente expresión regular:

User.EMAIL_REGEX = re.compile('[^@\\s]+@[^@\\s.]+(\\.[^@\\s.]+)+')¶

Y el nombre la siguiente:

User.NAME_REGEX = re.compile('[a-zA-Z0-9_]{4,12}')¶

La longitud de la contraseña tendrá que estar entre los dos valores siguientes:

User.MIN_PASSWORD_LENGTH = 6¶

User.MAX_PASSWORD_LENGTH = 30¶

También puede deberse a otros errores lógicos, como que se intente asignar a un usuario una foto de perfil o tapete que no haya comprado.

Cliente Básico¶

Dadas las restricciones anteriores, se describe a continuación cómo sería un cliente básico para acceder a la API de datos, que permite entender de forma sencilla el flujo de control de manejo de errores:

@startuml
!pragma useVerticalIf on

start

:Hacer petición;

if (¿se produjo un error?) then (sí)
if (error == 400) then (sí)
if (de quién es el fallo?) then (del usuario)
:Se le muestra el mensaje
de error del campo `error`;
else (del frontend)
stop

note right
Debug en el cliente y
solucionarlo, ya que no
es esperado que suceda.
Se puede usar el campo
`error` para ello.
end note
endif
elseif (error == 401) then (sí)
:Refrescar el token;

stop

note right
Reintentar petición
end note
elseif (error >= 500 && error <= 599) then (sí)
:Error en el backend;

stop

note right
Debug en el backend y
solucionarlo, que será
donde se encuentre más
información.
end note
endif
else (no)
:Se puede usar el valor devuelto;
endif

stop

@enduml

Referencia¶

gatovid.api.data.login(data)¶

Endpoint para iniciar la sesión con las credenciales de un usuario ya registrado. Debe cumplir los requisitos de Errores de Validación.

Parámetros

email (str) – Dirección de correo electrónico
password (str) – Contraseña

Devuelve

Un token de acceso en el campo access_token, o un error de validación.

gatovid.api.data.logout(data)¶

Endpoint autenticado para cerrar la sesión.

Devuelve: Un mensaje descriptivo de la operación realizada correctamente, o un mensaje de error interno en caso contrario.

gatovid.api.data.modify_user(data)¶

Endpoint autenticado de modificación del usuario, al cual se le pasan aquellos campos a cambiar, todos siendo opcionales. Los parámetros deben cumplir las reglas de validación establecidas en gatovid.models.User().

No hace falta pasar el email porque al estar protegido se puede obtener a partir del token. De esta forma se asegura que no se modifican los perfiles de otros usuarios.

Parámetros

name (Optional[str]) – Nombre nuevo del usuario
password (Optional[str]) – Contraseña nueva del usuario
board (Optional[int]) – El identificador del nuevo tapete del usuario
picture (Optional[int]) – El identificador de la nueva foto del usuario

Devuelve

Un mensaje descriptivo de la operación realizada correctamente, o un mensaje de error interno en caso contrario. Se considera un error el no indicar ninguno de los parámetros opcionales anteriores.

gatovid.api.data.protected(data)¶: Endpoint temporal para probar la autenticación con JWTs.

Advertencia

Esto será eliminado en el futuro.

gatovid.api.data.remove_user(data)¶

Endpoint autenticado de borrado de cuenta.

Al borrar una cuenta se cierra también la sesión, garantizando que solo se podrá borrar una vez.

Devuelve: Un mensaje descriptivo de la operación realizada correctamente, o un mensaje de error interno en caso contrario.

gatovid.api.data.shop_buy(data)¶

Endpoint para comprar un objeto en la tienda.

Parámetros

id (int) – Identificador del objeto
type (str) – Tipo del objeto («board» | «profile_pic»)

Devuelve

Un mensaje descriptivo de la operación realizada correctamente, o un mensaje de error interno en caso contrario.

gatovid.api.data.signup(data)¶

Endpoint de registro de un usuario. Los parámetros deben cumplir las reglas de validación establecidas en gatovid.models.User().

Parámetros

email (str) – Dirección de correo electrónico
name (str) – Nombre del usuario
password (str) – Contraseña del usuario

Devuelve

Un objeto JSON con el nombre y correo del usuario registrado, como forma de verificación de la operación, o un error de validación.

gatovid.api.data.test(data)¶: Endpoint de prueba que realiza una petición a la base de datos y devuelve los argumentos que se le han pasado.

Advertencia

Esto será eliminado en el futuro.

gatovid.api.data.user_data(data)¶

Endpoint autenticado para acceder a los datos personales de un usuario.

Devuelve: Un objeto JSON con los campos:

email: str
name: str
coins: int
picture: int (identificador)
board: int (identificador)
purchases: List[{"item_id": str, "type": ("board" | "profile_pic")}]

gatovid.api.data.user_stats(data)¶

Endpoint para acceder a las estadísticas de un usuario, dado su nombre.

Parámetros: name (str) – Nombre del usuario
Devuelve: Un objeto JSON con los campos games, losses, wins y playtime_mins, todos enteros.