Home - PabloGallazzi/java-spring GitHub Wiki

Welcome to the tp-tacs wiki!

API REST:

Todos los mensajes que no sean OK (es decir != 2xx) tendrán el formato:

{"message":"mensajeDescriptivo", "status":400,"error":"tipoDeError","cause":[]}

Donde cause es un array de String por ejemplo: ["user_name_already_used", "user_password_length_below_6_chars"].

Todas las respuestas pueden llegar a devolver los siguientes status de error, que aunque no deberían suceder, deben estar definidas, y poder ser manejadas.

FAILURE_RESPONSE_STATUS: 500 o 503, el 500 con body (el definido arriba), y el 503 sin body.

Además podrán retornar errores específicos que se especifican más adelante.

Los request deben ir autenticados, por el token que se generará en base al user y al password, y ese token tendrá scopes para la diferenciación de los usuarios admin y no admin. También se puede consultar el tipo de usuario directo a donde esté guardado el mismo, pero la idea es diferenciar el “scope” que va a tener el request. El token se envía en el query string con el nombre "access_token".

Si el request no esta autenticado y fuese requerido, se devuelve alguno de los siguientes según corresponda:

{"message":"Access token must be provided", "status":401,"error":"unauthorized","cause":[]}

{"message":"invalid_token", "status":401,"error":"unauthorized","cause":[]}

{"message":"Forbidden", "status":403,"error":"unauthorized","cause":[]}

#User Stories:

Como usuario quiero poder crear una cuenta con user y pass.

URI: /users

METHOD: POST

REQUEST_BODY :

{ "user_name": "unNombre", "user_password": "unaPassword"}

SUCCESS_RESPONSE_STATUS: 201

SUCCESS_RESPONSE_BODY :

{"user_name": "unNombre", "user_id": 123}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to create user", "status":400,"error":"validation_error","cause":[]}

En cause pueden venir, la combinación de alguno de estos

"user_name_already_used"

"user_password_length_below_6_chars"

"user_password_must_contain_one_of_|;,._-|"

"must_provide_a_password"

"must_provide_a_user_name"

Como usuario quiero poder loguearme a mi cuenta con user y pass.

URI: /users/authenticate

METHOD: POST

REQUEST_BODY :

{ "user_name": "unNombre", "user_password": "unaPassword"}

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

{"expiration_date":1460431274003,"access_token":"1-387cc2ae79133a-3ad50793d64f9a6f76","user_id":1,"scopes":["admin","read","write"]}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to authenticate user", "status":404,"error":"invalid_credentials","cause":[]}

Acá decidimos no especificar si lo que está mal es el usuario o la password por un tema de seguridad.

Como usuario quiero poder consultar el catálogo de personajes de Marvel utilizando la API provista por la compañía.

URI: /characters?sort=SORT&criteria=CRITERIA&offset=OFFSET&limit=LIMIT&name_starts_with=NAME_STARTS_WITH

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

{"paging": {"total":123,"limit":20,"offset":0} ,"results":[{"id": 123,"name":"nombre","description":"info"}]}

Donde los posibles valores son:

SORT : modified, name

CRITERIA : desc, asc

OFFSET : número (depende de la cantidad)

LIMIT : número (entre 1 y 100)

NAME_STARTS_WITH : nombre comienza con...

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to get characters", "status":400,"error":"bad_request","cause":["missing_param_limit","invalid_param_criteria"]}

Como usuario quiero ver cuales son mis personajes marcados como favoritos

URI: /users/{user}/characters/favorites

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

[{"id": 123,"name":"info","description":"info"}]

Como usuario quiero poder marcar / desmarcar personajes como mis favoritos.

URI: /users/{user}/characters/favorites/{id} (para ambos)

METHOD: DELETE

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 204

SUCCESS_RESPONSE_BODY : NO TIENE

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to remove characters", "status":400,"error":"bad_id","cause":["character_id_must_be_a_natural_number"]}

FAILURE_RESPONSE_STATUS: 404

FAILURE_RESPONSE_BODY :

{"message":"Unable to remove character","status":404,"error":"character_not_found","cause":[]}

METHOD: POST

REQUEST_BODY :

{"id": 123, "name":"nombre"}

SUCCESS_RESPONSE_STATUS: 201

SUCCESS_RESPONSE_BODY :

{"id": 123, "name":"nombre"}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to add characters", "status":400,"error":"bad_id","cause":["character_id_must_be_a_natural_number"]}

Como usuario quiero poder crear un grupo de personajes y ponerle nombre

URI: /users/{user}/teams

METHOD: POST

REQUEST_BODY :

{"team_name": "unNombre", "members": [{"id": 123, "name":"nombre"},{"id": 456,"name":"nombre"}]}

SUCCESS_RESPONSE_STATUS: 201

SUCCESS_RESPONSE_BODY :

{"team_id": 123, "team_name": "unNombre", "members": [{"id": 123,"name":"nombre"},{"id": 456,"name":"nombre"}]}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to crete team", "status":400,"error":"already_exists","cause":["team_name_already_exists"]}

Como usuario quiero poder consultar un grupo y sus personajes

URI: /users/{user}/teams/{team}

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

{"team_id": 123, "team_name": "unNombre", "members": [{"id": 123,"field1":"value","field2":"value"},{"id": 456,"field1":"value","field2":"value"}]}

FAILURE_RESPONSE_STATUS: 404

FAILURE_RESPONSE_BODY :

{"message":"Unable to get team", "status":404,"error":"not_found","cause":[]}

Como usuario quiero poder agregar un personaje a un grupo

URI: /users/{user}/teams/{team}/character

METHOD: POST

REQUEST_BODY :

{"id": 123,"name":"nombre"}

SUCCESS_RESPONSE_STATUS: 201

SUCCESS_RESPONSE_BODY :

{"id": 123,"name":"nombre"}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to add character", "status":400,"error":"bad_id","cause":["character_id_must_be_a_natural_number"]}

Como usuario quiero poder eliminar un personaje de un grupo

URI: /users/{user}/teams/{team}/character/{id}

METHOD: DELETE

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 204

SUCCESS_RESPONSE_BODY : NO TIENE

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to remove character", "status":400,"error":"bad_id","cause":["character_id_must_be_a_natural_number"]}

FAILURE_RESPONSE_STATUS: 404

FAILURE_RESPONSE_BODY :

{"message":"Unable to remove character", "status":404,"error":"not:_found","cause":[]}

Como administrador quiero poder ver los siguientes datos de un usuario:

User
Cantidad de grupos creados
Cantidad de personajes favoritos
Último acceso
Detalle de un grupo (nombre, personajes)

URIS:

/users/{user}

/users/{user}/teams/{team}

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

Acá entra en juego el tema de los scopes definido arriba.

Como administrador quiero tener un ranking de los personajes favoritos en la app.

URI: /characters/ranking?limit=LIMIT

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

[{"id": 123, "elected_times":10}]

LIMIT : número (entre 1 y 100)

Como administrador quiero seleccionar 2 grupos de usuarios diferentes y mostrar la intersección.

URI: /teams/commons/{id}/{id2}

METHOD: GET

REQUEST_BODY : NO TIENE

SUCCESS_RESPONSE_STATUS: 200

SUCCESS_RESPONSE_BODY :

[{"id": 123,"name":"nombre"}]

FAILURE_RESPONSE_STATUS: 404

FAILURE_RESPONSE_BODY :

{"message":"Unable to get commons", "status":404,"error":"not:_found","cause":["id $id not found","id2 $id not found"]}

FAILURE_RESPONSE_STATUS: 400

FAILURE_RESPONSE_BODY :

{"message":"Unable to get commons", "status":400,"error":"not:_found","cause":["team_id_must_be_a_natural_number"]}