Introducción
La calificación sirve para dar un voto y un comentario a las recetas y otras entidades de kiwilimón.
El usuario *tiene que estar conectado* para poder calificar.
La calificación en sí es un valor de 1 a 5, representado por estrellas, de 1 a 5 estrellas.
El comentario es libre. Ya no hay título.
Solamente se permite una calificación por receta por chef.
Alrededor del comentario, el usuario en general puede votar "Up" y "Down" o sea un voto positivo o negativo para los demás comentarios que no son suyos.
También se puede "denunciar" un comentario.
Cualquier interacción necesita un usuario conectado.
Los comentarios se pueden contestar, pero únicamente con el cuerpo del comentario (sin estrellas)
Las respuestas no tienen "Up" ni "Down" , pero sí tambien tienen la posibilidad de denunciar la entrada.
Cabe notar que los usuarios pueden contestar cuantas veces quieren
Recurso GET 'data'
Los datos de las calificaciones se pueden consultar de la manera siguiente:
[GET] /v2/calificacion/:Token/:Clave/:Primero/:Cantidad/:orden/data.json
:Token es el token del chef conectado, o 'r' si no esta conectado.
:Clave es la clave de la receta (del tipo consultado).
:Primero: es el primer objeto de la lista que necesitamos. 0 indica que no hay offset y apunta el primero de la lista. De 1 en adelante es un offset para saltar cantidad de objetos en la lista total.
:Cantidad: es la cantidad de objetos que queremos regresar a partir del "primero" solicitado.
:orden: es el campo de ordenamiento. Si este campo esta omitido, el sistema regresa el ordenamiento por defecto que es por fecha más reciente.
Valores posibles del ordenamiento:
fecha: Enseña los más recientes primero. Es la opción por defecto
importante: Enseña las calificaciones más votadas "Up".
calificacion: Enseña las calificaciones más altas primero.
El sistema regresará los datos de las calificaciones solicitadas:
{ total: 120,
calificaciones:
[
{CALIFICACION1},
{CALIFICACION2},
...
]
chef:{CALIFICACION}
}
: contiene la cantidad total de comentarios accesibles.
chef: presente si el chef esta identificado con token Y si ha calificado esta receta.
Cada calificación tiene los campos:
{
"clave": 1,
"calificacion": 5,
"comentario": "Comentario de la calificacion",
"up": 10,
"down": 1,
"chef": 100000,
"chefnombre": "Pedrito",
"chefavatar": "https://facebook.com/imagen/pedrito.jpg",
"respuestas": [
{SUBCALIFICACION1},
{SUBCALIFICACION2},
]
}
Cada subcalificación tiene los campos:
{
"clave": 2,
"comentario": "Respuesta a la calificacion",
"chef": 100000,
"chefnombre": "Pedrito",
"chefavatar": "https://facebook.com/imagen/pedrito.jpg",
}
Los campos a considerar son:
clave: la clave interna de referencia de la calificación en el GRAPH.
calificación: el valor de la calificación, 1 a 5.
comentario: el comentario escrito con la calificación.
up: la cantidad de veces que los usuarios votarón positivo para esta calificación.
down: la cantidad de veces de los usaurios votarón negativo para esta calificación.
chef: la clave del chef que hizo la calificación/comentario.
chefnombre: el nombre del chef que hizo la calificación/comentario.
chefavatar: el avatar del chef que hizo la calificación/comentario.
respuestas: el arreglo de las distintas respuestas a este comentario.
Recurso POST
Este recurso permite enviar una calificación con su comentario:
Cabe notar que el sistema solamente acepta una calificación por usuario por cada tipo/clave enviado. Es decir que el usuario no puede calificar dos veces la misma receta. Por praticidad, si el usuario ya habia calificado esta tipo/clave entonces será modificado, sino será agregado.
NOTA IMPORTANTE:
Por el momento no se usan las respuestas. Si bien el sistema puede enviar comentarios con respuestas, que desplegamos al lector, no se puede tocar estas respuestas (ni agregar nuevas ni modificar las que estan).
En otras palabras, siempre padre sera NULL y calificacion siempre con un valor de 1 a 5.
El sistema acepta solamente UNA calificacion por chef conectado y por receta. Si el recurso detecta que ya existe la calificación entonces la reemplazara en lugar de insertar una nueva.
Los parámetros a enviar al POST son los siguientes:
token = el token del chef conectado.
calificacion = la calificación dada, de 1 a 5. Obligatoria
comentario = el comentario. texto libre.
clave = la clave de la receta para enviar la calificación.
formato: Es el formato en el cual queremos los resultados. Es uno de 'json', 'xml' o 'txt. Es un parámetro opcional, y si no esta especificado regresa un JSON por defecto.
Si todo funciona bien, el servicio regresa:
{"estatus":"OK", "clave": 123}
clave = es la clave interna de la nueva calificación.
En caso de error, el servicio regresa el siguiente formato:
{"estatus":"Error","message":"La calificación no esta en el rango autorizado (1-5)"}
estatus = Error, invariable.
message = el mensaje del error.
Recurso PUT
NOTA IMPORTANTE:
Por el momento no se usa este servicio (votar "Up", "Down" y "Denunciar").
Este recurso permite enviar datos ligados a una calificación:
Los parámetros a enviar al PUT son los siguientes:
token = el token del chef conectado.
clave = la clave de la receta para enviar la calificación.
orden = el evento que queremos consignar: "up" para enviar un voto positivo, "down" para enviar un voto negativo, "denuncia" para denunciar el comentario.
Si todo funciona bien, el servicio regresa:
{"estatus":"OK", "clave": 1, "up": 10, "down": 1}
clave = es la clave interna de la calificación.
up = la cantidad de votos positivos resultantes.
down = la cantidad de votos negativos resultantes.
En caso de error, el servicio regresa el siguiente formato:
{"estatus":"Error","message":"La clave no existe"}
estatus = Error, invariable.
message = el mensaje del error.
