Descripción del API REST de la aplicación Vocabulary

En este artículo se describe de forma teórica los endpoint necesarios para cubrir las necesidades funcionales de la aplicación Vocabulary.

Los detalles de la implementación serán tratados más adelante en la parte servidora.

La aplicación cliente, cuando es usada por los usuarios no administradores necesitan realizar las siguientes operaciones:

Desde la perspectiva del administrador, necesitamos además las siguientes operaciones:

Cada operación de negocio está asociada a un endpoint, siendo un endpoint la combinación de una URL, un verbo HTTP y opcionalmente unos parámetros de entrada, usaremos JSON como formato de intercambio de datos.

Por convenio, los verbos HTTP suelen ser usados para:

Endpoints de la aplicación

   El icono implica que es un endpoint protegido disponible para administradores.

Más adelante se describe cómo se realiza la protección de los EndPoint del API.

Recuperación de las preguntas

HTTP GET /v1/api/questions

Formato respuesta:

    [ 
      {"id":"1", "state":1, "translates": [{"lang":"es","text":"casa"},  {"lang":"en","text":"house"}]},
      {"id":"2", "state":1, "translates": [{"lang":"es","text":"libro"}, {"lang":"en","text":"book" }]},
      {"id":"3", "state":1, "translates": [{"lang":"es","text":"mesa"},  {"lang":"en","text":"table"}]},
      {"id":"4", "state":1, "translates": [{"lang":"es","text":"árbol"}, {"lang":"en","text":"tree" }]}
    ]

Sugerencia de una pregunta

HTTP POST /v1/api/questions

Formato de la petición:

{"id":0, "state":0, "translates":[{"lang":"es","text":"cuchara"}, {"lang":"en","text":"spoon"}]}

Formato respuesta:

{"httpStatusCode":"OK","apiCode":"OK","message":"91a7cff1"}

Obtener una palabra del vocabulario

HTTP GET /v1/api/questions/{nativeLanguage}/{learnLanguage}

Por ejemplo, en un usuario cuyo idioma nativo es el español y desee aprender aprender inglés la url necesaria sería /v1/api/questions/es/en

Formato respuesta:

{"id":"2", "state":1, "translates": [{"lang":"es","text":"libro"}, {"lang":"en","text":"book" }]}

Actualización de una pregunta

HTTP PUT /v1/api/questions

Formato de la petición:

{"id":"91a7cff1", "state":0, "translates":[{"lang":"es","text":"cuchara"}, {"lang":"en","text":"spoon"}, {"lang":"fr","text":"cuillère"}]}

(Actualizaría la pregunta anterior agregando la traducción al Francés)

Formato respuesta:

{"httpStatusCode":"OK","apiCode":"OK","message":"91a7cff1"}

Eliminación de una pregunta

HTTP DELETE /v1/api/questions/91a7cff1

Formato respuesta:

{"httpStatusCode":"OK","apiCode":"OK","message":"91a7cff1"}

La pregunta con ID 91a7cff1 ha sido correctamente eliminada.

Cambiar a 'publicado'/'no publicado' el estado de una pregunta

HTTP PUT /v1/api/questions/{id}/state/{on | off}

Formato respuesta:

{"httpStatusCode":"OK","apiCode":"OK","message":"{"id":"5ea26859", "state":1}"}

Cuando apiCode es OK, el valor de message.state indica cual es el estado actual de la pregunta.
Si vale 1 indica que la pregunta es visible, es decir, está publicada. En caso contrario es que no está visible.

Recuperación de una pregunta

HTTP GET /v1/api/questions/{id}

Formato respuesta:

{"id":"2", "state":1, "translates": [{"lang":"es","text":"libro"}, {"lang":"en","text":"book" }]}

Usado desde la zona de administración para editar una pregunta.

Protección de los endpoints

Para todas la solicitudes a URL protegidas, es necesario especificar en la cabecera HTTP XAuth-Token o en un parámetro de la petición de nombre token el valor del token de acceso obtenido al iniciar sesión. (Lo hace la parte cliente de forma transparente).

Todas las peticiones en endpoints protegidos que no incluyan la cabecera Auth-Token o que el token haya caducado generará una respuesta con código HTTP 401 (Unauthorized) y con contenido:

{
    httpStatusCode: "UNAUTHORIZED",
    apiCode: "ACCESS_DENIED",
    message: "Access is denied"
}

Los detalles de la implementación serán tratados más adelante en la parte servidora.