MICROSITIOS. Perfiles

Transcripción

1 MICROSITIOS Perfiles API para el consumo de servicios encargados de la creación, visualización, edición, eliminación y demás operaciones sobre los perfiles de usuarios de Metaportal. METAPORTAL 18/07/2014

2 Contenido Operaciones del API (Usuarios)... 3 Listar usuarios Procedimiento... 3 Posibles Respuestas... 3 Visualización de plantilla Procedimiento... 5 Posibles Respuestas... 6 Ver perfil Procedimiento... 7 Posibles Respuestas... 7 Crear perfil Procedimiento... 9 Posibles Respuestas... 9 Editar perfil Procedimiento Posibles Respuestas Eliminar perfil Procedimiento Posibles Respuestas Crear campo adicional Procedimiento Posibles Respuestas Ver información de un campo específico Procedimiento Posibles Respuestas Editar información de un campo específico Procedimiento Posibles Respuestas Operaciones del API (Roles) Listar Roles Procedimiento Posibles Respuestas Ver Rol Procedimiento Posibles Respuestas... 29

3 Crear Rol Procedimiento Posibles Respuestas Editar Rol Procedimiento Posibles Respuestas Eliminar Rol Procedimiento Posibles Respuestas... 38

4 Operaciones del API (Usuarios) Listar usuarios. Una de las funcionalidades del api de perfiles de Metaportal consiste en listar los usuarios existentes en la base de datos. Los datos son mostrados en formato Collection+JSON - Hypermedia Type. Procedimiento 1. Por medio del método GET y la URL especificada se podrá recuperar la información de los usuarios. URL de consumo (GET) /api/v1/users Datos permitidos que se recibirán: En esta operación no son necesarios datos adicionales a la URL especificada. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (GET) En el listado de usuarios, según la cantidad de registros la respuesta se genera paginada, en estos casos la respuesta viene con una posición adicional en el arreglo (links). URL s: En caso de no colocar el parámetro page en la URL, por defecto la página mostrada será la primera. Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej.

5 2. Si no hay usuarios para listar en la base de datos (tabla vacía). 3. Si la operación se efectúa con éxito se listan los usuarios en el formato correspondiente. Por efectos de visualización en la imagen se omiten parámetros, por tal motivo se listan a continuación. Parámetros básicos de la lista de usuarios mostrados: user_id, name, last_name, mail, pass, status, theme, signature, signature_format, created, access, login, timezone, language, picture, init, data. Adicional a los parámetros básicos, los campos correspondientes a los usuarios son dinámicos, es decir que si se agregan campos adicionales, estos también serán mostrados en el listado de usuarios Ej. phone, address. Cada usuario creado en la base de datos tiene uno o varios perfiles asociados, por tal razón en el listado son mostrados como parte de la información del usuario.

6 Visualización de plantilla. Una de las opciones que ofrecida al consumir el servicio que lista los usuarios, es la posibilidad de mostrar solo la plantilla ( template ) como guía para la creación, edición o futuras operaciones que se vayan a realizar. Para obtener dicha plantilla se debe enviar un parámetro adicional a la URL, el cual indicará que solamente se desea consultar el esqueleto. Procedimiento 1. Por medio del método GET y la URL especificada se podrá recuperar la plantilla de usuarios. URL de consumo (GET)

7 Datos permitidos que se recibirán: Como parámetro adicional para consultar la plantilla es necesario solo_template y su valor debe ser verdadero ( true ) tal como se indica en la URL inmediatamente anterior. En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (GET) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si la operación se efectúa con éxito se listan los campos disponibles con valores vacíos. Si es necesario adicionar roles a determinado usuario, en la parte final de la plantilla se agrega un campo de tipo arreglo en el cual se indican los Id s de los roles que correspondan.

8 Ver perfil. Otra de las funcionalidades del API de perfiles es poder ver en detalle la información de un único usuario, indicando en la URL su identificador. Procedimiento 1. Por medio del método GET y la URL especificada se podrá recuperar la información de un usuario específico. URL de consumo (GET) Datos permitidos que se recibirán: Es necesario dentro de la URL colocar como último parámetro el identificador del usuario que se desea consultar. En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (GET) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML

9 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si no existe el usuario solicitado.

10 3. Si la operación se realizó de forma exitosa. Crear perfil. Para realizar la creación de un nuevo usuario con el API de perfiles es necesario que el consumidor suministre la información del usuario y sus roles de acuerdo a la plantilla ( Visualización de plantilla ). Procedimiento 1. Por medio del método POST, la URL especificada y los parámetros necesarios se podrá crear un usuario nuevo. Posibles Respuestas URL de consumo (POST) Datos necesarios: Todos aquellos datos generados en la plantilla correspondientes a información del usuario y roles asociados. Los datos deben ser enviados con la estructura application/vnd.collection+json. En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (POST) Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej.

11 2. En caso de que el formato en el cual se envía la información tenga malformaciones. 3. En caso de que la plantilla esté bien formada en su estructura, pero no tenga datos internos.

12 4. Por estructura application/vnd.collection+json cada tato enviado está compuesto por un name, value y prompt, por lo tanto si por error se altera alguno de estos parámetros se obtiene una respuesta errónea. 5. Si toda la estructura de la plantilla está correcta pero los campos obligatorios no contienen información. (user_id, name, last_name, mail)

13 6. Si se presenta alguna excepción durante la operación. 7. Si se presenta algún error agregando los roles del usuario.

14 8. Si alguno de los campos enviados en la plantilla no existe en la tabla de usuarios. 9. Si la operación se realizó con éxito no se retorna información, simplemente en el encabezado se coloca como estado 201 (Creado). Editar perfil. Para realizar la edición de un usuario con el API de perfiles es necesario que el consumidor suministre la información del usuario y sus roles de acuerdo a la plantilla ( Visualización de plantilla ).

15 Procedimiento 2. Por medio del método PUT, la URL especificada (incluido el Id del usuario) y los parámetros necesarios se podrá editar un usuario determinado. Posibles Respuestas URL de consumo (POST) Datos necesarios: Todos aquellos datos generados en la plantilla, correspondientes a información del usuario que sea necesario editar. Los datos deben ser enviados con la estructura application/vnd.collection+json. En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (POST) Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej En caso de que el usuario que se desea editar no exista. 3. En caso de que el formato en el cual se envía la información tenga malformaciones.

16 4. En caso de que la plantilla esté bien formada en su estructura, pero no tenga datos internos. 5. Por estructura application/vnd.collection+json cada tato enviado está compuesto por un name, value y prompt, por lo tanto si por error se altera alguno de estos parámetros se obtiene una respuesta errónea.

17 6. Si toda la estructura de la plantilla está correcta pero los campos obligatorios no contienen información. (user_id, name, last_name, mail) 7. Si se presenta alguna excepción durante la operación.

18 8. Si se presenta algún error agregando los roles del usuario. 9. Si alguno de los campos enviados en la plantilla no existe en la tabla de usuarios.

19 10. Si la operación se realizó con éxito se muestra la información del usuario editada. Eliminar perfil. Para realizar la eliminación de un usuario con el API de perfiles es necesario que el consumidor suministre en la URL el identificador del usuario que desea eliminar. La eliminación de las relaciones (Perfiles e información de campos adicionales) se realizará en cascada, es decir que eliminado un usuario se elimina toda la información asociada al mismo. Procedimiento 3. Por medio del método DELETE y la URL especificada (incluido el Id del usuario) se podrá eliminar un usuario determinado. Posibles Respuestas URL de consumo (DELETE) Datos necesarios: Solamente requiere que en la URL se especifique el identificador del usuario. En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (DELETE) Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej.

20 2. En caso de que el usuario que se desea eliminar no exista. 3. Si la operación se realizó con éxito no se retorna información, simplemente en el encabezado se coloca como estado 204 (Sin contenido).

21 Crear campo adicional. Para realizar la creación de un campo adicional para la tabla de usuarios con el API de perfiles es necesario que el consumidor suministre el nombre del nuevo campo (atributo) y opcionalmente el tipo de campo. Las respuestas se mostrarán en formato application/vnd.collection+json o XML. Procedimiento 4. Por medio del método PUT, la URL especificada y los datos mencionados se podrá crear un campo adicional para incluir información de perfil correspondiente a un usuario. URL de consumo (PUT) Datos necesarios: Obligatoriamente requiere el parámetro atributo correspondiente al nombre del nuevo campo, este debe ser en minúscula y sin espacios, en caso de requerir un separador de palabras puede usar guión bajo. Opcionalmente puede suministrar el tipo de dato a almacenar (entero, flotante, texto, fecha), si no se especifica por defecto será texto. {"atributo":"atributo_nuevo", "tipo":"texto"} En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (PUT) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML. 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej En caso de que no se envíen datos para la creación del nuevo campo o de que los datos enviados no correspondan a los solicitados.

22 3. Si se envía el parámetro tipo, pero el valor no corresponde a un tipo de dato válido 4. Si ya existe un campo con el nombre que desea asignar.

23 5. Si el nombre del campo tiene caracteres inválidos. 6. Si la operación se realizó con éxito no se retorna información, simplemente en el encabezado se coloca como estado 201 (Creado).

24 Ver información de un campo específico. Esta funcionalidad del API permite ver la información específica de un campo que el consumidor requiera, para un usuario determinado. Las respuestas se mostrarán en formato json o XML. Procedimiento Por medio del método GET y la URL especificada se podrá consultar la información de un campo específico del perfil de un usuario. URL de consumo (GET) En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (GET) Posibles Respuestas Las respuestas se pueden generar en formato json o XML. 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej En caso de que el usuario del cual se requiere información no exista.

25 3. En caso de que el atributo solicitado no exista. 4. Si la operación se realizó con éxito. Editar información de un campo específico. Esta funcionalidad del API permite editar la información específica de un campo que el consumidor requiera, para un usuario determinado. Las respuestas se mostrarán en formato json o XML. Procedimiento Por medio del método PUT, la URL especificada y el nuevo valor del campo se podrá realizar la edición. URL de consumo (PUT) Parámetros: JSON con el atributo valor {"valor":"nuevo valor"}.

26 En ciertos casos la URL puede cambiar si la respuesta se requiere en formato XML, para este caso la URL de consumo es (PUT) Posibles Respuestas Las respuestas se pueden generar en formato json o XML. 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej En caso de que el usuario no exista. 3. En caso de que el atributo solicitado no exista.

27 4. Si no se envía el parámetro valor para el atributo a editar. 5. Si la operación se realizó con éxito no se retorna información, simplemente en el encabezado se coloca como estado 200 (Ok).

28 Operaciones del API (Roles) Listar Roles Ofrece el listado de los roles disponibles en la base de datos. Los datos son mostrados en formato Collection+JSON - Hypermedia Type. Procedimiento 1. Por medio del método GET y la URL especificada se podrá recuperar la información de los roles disponibles. URL de consumo (GET) Datos permitidos que se recibirán: En esta operación no son necesarios datos adicionales a la URL especificada. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (GET) Para facilitar al consumidor el formato en el cual debe enviar los datos para realizar la creación y la edición de un rol, a la URL especificada anteriormente se le agrega el parámetro solo_template con valor true (GET) (GET) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si la tabla de roles está vacía

29 3. Si la operación se realizó con éxito se muestra el listado de roles. 4. Si se requiere solo la plantilla ( template ) indicando en la URL?solo_template=true

30 Ver Rol Funcionalidad encargada de mostrar el detalle de un rol determinado. Los datos son mostrados en formato Collection+JSON - Hypermedia Type. Procedimiento 2. Por medio del método GET y la URL especificada (incluido el identificador del rol) se podrá recuperar la información del Rol requerido. Posibles Respuestas URL de consumo (GET) Datos permitidos que se recibirán: En esta operación no son necesarios datos adicionales a la URL especificada. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (GET) Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej En caso que no exista el Rol solicitado.

31 3. Si la operación se realiza con éxito se muestra la información del Rol solicitado.

32 Crear Rol Funcionalidad encargada de crear un rol en la base de datos según unos parámetros dados. Las respuestas son mostradas en formato Collection+JSON - Hypermedia Type. Procedimiento Por medio del método POST, la URL especificada y los datos correspondientes, se podrá crear un nuevo rol en la base de datos. URL de consumo (POST) Datos permitidos que se recibirán: Todos aquellos correspondientes a los atributos de la tabla roles. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (POST) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si la plantilla en la cual se envían los datos no existe o existe con malformaciones. 3. Si existe la plantilla pero el arreglo de datos está vacío

33 4. Si existen parámetros requeridos sin información. 5. Si a la estructura de la plantilla le hace falta un parámetro nombre o valor.

34 6. Si alguno de los parámetros enviados no corresponde a los atributos del Rol 7. Si la operación se realizó con éxito.

35 Editar Rol Funcionalidad encargada de editar un rol existente en la base de datos según unos parámetros dados. Las respuestas son mostradas en formato Collection+JSON - Hypermedia Type. Procedimiento Por medio del método PUT, la URL especificada y los datos correspondientes, se podrá editar un rol existente en la base de datos. URL de consumo (PUT) Datos permitidos que se recibirán: Todos aquellos correspondientes a los atributos de la tabla roles. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (PUT) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si la plantilla en la cual se envían los datos no existe o existe con malformaciones.

36 3. Si existe la plantilla pero el arreglo de datos está vacío 4. Si existen parámetros requeridos sin información. 5. Si a la estructura de la plantilla le hace falta un parámetro nombre o valor.

37 6. Si alguno de los parámetros enviados no corresponde a los atributos del Rol 7. Si el rol buscado no existe.

38 8. Si la operación se realiza con éxito se muestra la información del Rol editado.

39 Eliminar Rol Funcionalidad encargada de eliminar un rol existente en la base de datos. Las respuestas son mostradas en formato Collection+JSON - Hypermedia Type. Procedimiento Por medio del método DELETE y la URL especificada (incluido el identificador del Rol), se podrá eliminar un rol existente en la base de datos. URL de consumo (DELETE) Datos permitidos que se recibirán En esta operación no son necesarios datos adicionales a la URL especificada. En ciertos casos la URL puede cambiar si el formato de respuesta se requiere en XML, para este caso la URL de consumo es (DELETE) Posibles Respuestas Las respuestas se pueden generar en formato application/vnd.collection+json o XML 1. En caso de que la URL de consumo finalice con un formato no válido (distinto a json o XML), por ejemplo si por accidente se envió con un carácter adicional Ej Si el Rol que se desea eliminar no existe.

40 3. Si la operación se realiza con éxito.