EsquemasAPI

Se trata de un framework sencillo orientado a presentar desafíos en un concurso a los distintos usuarios, y premiar al que gane más puntos resolviendo los desafíos.

Funcionamiento general

A grandes rasgos, los esquemas son:

• existen Users
• existen Challenges
• existen Contests

Los Contests están formados por un grupo de Users participantes y Challenges a resolver. Un Contest tiene un ID único, inicio, duración y un listado de reglas a cumplir por los participantes (estas reglas no se aplican a nivel sistema, sino a nivel humano). El Contest actual recibe un nombre especial: current, sin alterar su ID. En este, la suma de inicio + duración será inferior al tiempo actual.

Los Users resuelven Challenges para sumar puntos durante un Contest. Fuera de un Contest, no se aceptan soluciones para los Challenges.

Los Challenges poseen un ID único (sin importar el Contest), nombre, puntaje otorgado al resolverlo, descripción y - opcionalmente - un listado de ayudas. Al resolver uno, no importa en qué Contest se encuentre, el User sumará puntos de ese Challenge. A modo de histórico, se identifica el Contest durante el cual el User lo resolvió. Si otro Contest futuro usase el mismo Challenge, al participar el User sumaría automáticamente los puntos correspondientes.

Para enviar soluciones de Challenges, el User debe estar registrado/con sesión iniciada. En el momento que lo hace, automáticamente está participando del Contest actual, que de no existir, no puede enviar soluciones. La API debe limitar los reintentos fallidos a los efectos de no permitir un ataque por fuerza bruta. Por ejemplo cada 5 reintentos, 1h de penalización.

Al resolver correctamente un Challenge, el sistema devuelve un token verificador que se utiliza para validar dicha situación, en caso de falla u otra situación desfaborable al usuario o al sistema. Este token es un string hexadecimal de 32 caracteres que se forma con una llave y token del sistema, el nombre del usuario y el ID del desafío. Pseudocódigo: proof = hmac_blake2b(data='SYSTEM_PROOF_TOKEN + USERNAME + CHALLENGE_ID', key='SYSTEM_PROOF_KEY', size='32').

Siempre que se produzca un error, cualquiera sea, la respuesta será un código único de error, en la forma {"error":"<error id>"}. Debe consultarse al recurso Errors para determinar su significado.

Esquema del recurso Contests

id:             Unique identifier among Contests.
name:           Friendly Contest name.
begin:          Unix timestamp of the start time.
lifespan:       Duration of the Contest, in seconds.
rules:          [Optional] List of human rules for 
                the Contest.
users:          List of Users participating in the 
                Contest. 
challenges:     List of Challenges in the Contest.
scores:         Collection of total score per User 
                for the Contest.

Esquema del recurso Challenges

id:             Unique identifier among Challenges.
name:           Friendly Challenge name.
score:          Ammount of points it gives when solved.
description:    Full description of the Challenge, and 
                how the solution must be provided.
hints:          [Optional] List of hints as a help to 
                solve the Challenge.
users:          List of Users that solved the 
                Challenge (among all Contests).
contests:       List of Contests where the
                Challenge was solved.

Esquema del recurso Users

username:       Unique identifier among Users.
password:       Secret to authenticate a User.
score:          Total score among all Contests.
challenges:     List of solved challenges, among 
                all Contests.
contests:       List of Contests in which the User 
                participates.

Esquema del recurso Errors

id:             Unique identifier among Errors.
type:           Type of Error.
description:    Description of the Error.