API Grupos
- Netex Sistemas
Owned by Netex Sistemas
Usar codificación de caracteres UTF-8 en el envío de datos
Manual de autenticación y versionado: manual (autenticación y versionado)
Por motivos de seguridad el external_id no puede contener los caracteres \ ni / (http://tomcat.apache.org/security-6.html).
Crear grupo/subgrupo
Método: POST
URL: /admin/rest/administration/api/groups
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups
- Formulario:
- external_id=exg1&name=Grupo1&description=Grupo para alumnos aula 1&parentId=1234&extendedField[Intercambio]=true&extendedField[Deporte]=1
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Parámetros
- external_id = Id externo (String, obligatorio).
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni / - name = Nombre del grupo (sin comas) (String, obligatorio)
- description = Descripción del grupo (String, opcional)
- parentId = Id del grupo padre si se está creando un subgrupo (Long, opcional)
- extendedField[nombre del campo extendido] (lista) = Nombre y valor de los campos extensibles (clave-valor de Strings, opcional*)
* solo son obligatorios aquellos campos extensibles que estén marcados como obligatorios y no tengan definido ningún valor por defecto- Valores permitidos:
- Si el campo extendido es de tipo texto --> cualquier texto
- Si el campo extendido es de tipo entero --> sólo números
- Si el campo extendido es de tipo si/no --> valores "true" o "false"
- Si el campo extendido es de tipo lista de valores --> un valor válido de la lista
- Valores permitidos:
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- El external id nuevo ya existe en un grupo --> Error ERR006 / 400 (Bad Request)
- El parent id es incorrecto --> Error GRP001 / 400 (Bad Request)
- El nombre no es válido, las comas no están permitidas --> Error GRP004 / 400 (Bad Request)
- El nombre de un campo extensible no existe --> Error DYN001 / 400 (Bad Request)
- El valor de un campo extensible tiene tipo incorrecto --> Error DYN002 / 400 (Bad Request)
- Falta algun campo extensible obligatorio --> Error DYN003 / 400 (Bad Request)
- No se ha incluido el campo obligatorio en la petición y no tiene asignado el valor por defecto
- Se ha incluido el campo en la petición pero se le ha asignado un valor vacío
Respuesta OK
- 201 (Created) + cabecera 'Location' con el link al recurso creado
Modificar grupo/subgrupo
Método: PUT
URL:
- Modificar por id:
- /admin/rest/administration/api/groups/id/{id}
- Modificar por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487
- Formulario:
- external_id=exg1&name=Grupo1&description=Grupo para alumnos aula 1&parentId=1234&extendedField[Intercambio]=true&extendedField[Deporte]=1
Parámetros
- external_id = Id externo nuevo (String, obligatorio) Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
- name = Nombre del grupo (sin comas) (String, obligatorio)
- description = Descripción del grupo (String, opcional)
- parentId = Id del grupo padre si se está creando un subgrupo (Long, opcional)
- extendedField[nombre del campo extendido] (lista) = Nombre y valor de los campos extensibles (clave-valor de Strings, opcional*)
* solo son obligatorios aquellos campos extensibles que estén marcados como obligatorios y no tengan definido ningún valor por defecto- Valores permitidos:
- Si el campo extendido es de tipo texto --> cualquier texto
- Si el campo extendido es de tipo entero --> sólo números
- Si el campo extendido es de tipo si/no --> valores "true" o "false"
- Si el campo extendido es de tipo lista de valores --> un valor válido de la lista
- Valores permitidos:
NOTA: Los campos no obligatorios que vayan vacíos se borrarán.
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir --> Error ERR001 / 400 (Bad Request)
- No existe el grupo --> Error 404 (Not Found)
- El external id nuevo ya existe en un grupo --> Error ERR006 / 400 (Bad Request)
- El parent id es incorrecto --> Error GRP001 / 400 (Bad Request)
- El nombre no es válido, las comas no están permitidas --> Error GRP004 / 400 (Bad Request)
- El nombre de un campo extensible no existe --> Error DYN001 / 400 (Bad Request)
- El valor de un campo extensible tiene tipo incorrecto --> Error DYN002 / 400 (Bad Request)
- Falta algun campo extensible obligatorio --> Error DYN003 / 400 (Bad Request)
- No se ha incluido el campo obligatorio en la petición y no tiene asignado el valor por defecto
- Se ha incluido el campo en la petición pero se le ha asignado un valor vacío
- Todo OK --> 200 (OK)
Obtener grupo
Método: GET
URL:
- Obtener por id:
- /admin/rest/administration/api/groups/id/{id}
- Obtener por external id:
- /admin/rest/administration/api/groups/externalid/{external_id}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Campos devueltos en el Json
Grupo, cada grupo consta de los siguientes campos:
- id = Identificador
- external_id = Id externo.
- parentId = Identificador de grupo padre
- name = Nombre de grupo
- description = Descripción de grupo
- extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValue
Validaciones
- No existe el grupo Error 404 (Not Found)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
Obtener grupos raíz sin paginar
Método: GET
URL: /admin/rest/administration/api/groups
Ejemplo:
Campos devueltos en el Json
Listado de grupos raíz, cada grupo consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- parentId = Id del grupo al que pertenece en caso de que sea un grupo
- name = Nombre
- description = Descripción
- extendedFields = Campos extensibles
Validaciones
- El grupo no existe --> Error 404 (Not Found)
- El grupo no tiene subgrupos --> Error 204 (No Content)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
Obtener subgrupos de un grupo
Método: GET
URL:
- Obtener por id:
- /admin/rest/administration/api/groups/id/{id}/subgroups
- Obtener por external id:
- /admin/rest/administration/api/groups/externalid/{external_id}/subgroups
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Campos devueltos en el Json
Listado de subgrupos, cada subgrupo consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- parentId = Id del grupo al que pertenece en caso de que sea un subgrupo
- name = Nombre
- description = Descripción
- e xtendedFields = Campos extensibles
Validaciones
- El grupo no existe --> Error 404 (Not Found)
- El grupo no tiene subgrupos --> Error 204 (No Content)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
Eliminar grupo/subgrupo
Método: DELETE
URL:
- Eliminar por id:
- /admin/rest/administration/api/groups/id/{id}
- Eliminar por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Cabeceras
- NLC-includeSubgroups: Opcional, valores permitidos:
- true: se borrarán también todos los subgrupos que cuelguen del grupo borrado
- false: no se borrarán subgrupos. Si el grupo tiene subgrupos dará un error de validación.
- El valor por defecto es false.
Validaciones
- No existe el grupo --> Error 404 (Not Found)
- El grupo tiene subgrupos --> Error 400 (Bad Request)
- Todo OK --> 200 (OK)
Añadir usuarios a un grupo/subgrupo (v1)
Método: POST
URL:
- Añadir por id:
- /admin/rest/administration/api/groups/id/{id}/users?action={action}
- Añadir por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=addByUserIds
- Formulario:
- id=51476&id=654165&id=6566
Parámetros
- action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
- Valores permitidos
- addByUserIds
- addByUserExternalids
- Valores permitidos
- id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Campos devueltos en el Json (en caso de que algún usuario haya dado error)
- status: KO
- ids / external ids: listado de ids o external ids que han dado error
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
- Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
- No existe el grupo --> Error 400 (Not Found)
- Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
- Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON
Añadir usuarios a un grupo/subgrupo (v2)
Método: POST
URL:
- Añadir por id:
- /admin/rest/administration/api/groups/id/{id}/users?action={action}
- Añadir por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=addByUserIds
- Formulario:
- id=51476&id=654165&id=6566
Parámetros
- action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
- Valores permitidos
- addByUserIds
- addByUserExternalids
- Valores permitidos
- id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Campos devueltos en el Json (en caso de que algún usuario haya dado error)
- status: KO
- ids / external ids: listado de ids o external ids que han dado error y los códigos de error
- GRP002: El usuario no existe
- GRP003: El usuario ya existe en el grupo
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
- Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
- No existe el grupo --> Error 400 (Not Found)
- Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
- Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON
Obtener los usuarios de un grupo/subgrupo
Método: GET
URL:
- Obtener por id:
- Sin paginación: /admin/rest/administration/api/groups/id/{id}/users
- Sin paginación versión reducida: /admin/rest/administration/api/groups/id/{id}/users&reduced=true
- Con paginación: /admin/rest/administration/api/groups/id/{id}/users?startIndex={startIndex}&count={count}
- Con paginación versión reducida: /admin/rest/administration/api/groups/id/{id}/users?startIndex={startIndex}&count={count}&reduced=true
- Obtener por external id:
- Sin paginación: /admin/rest/administration/api/groups/externalid/{external_id}/users
- Sin paginación versión reducida: /admin/rest/administration/api/groups/externalid/{external_id}/users&reduced=true
- Con paginación: /admin/rest/administration/api/groups/externalid/{external_id}/users ?startIndex={startIndex}&count={count}
- Con paginación versión reducida: /admin/rest/administration/api/groups/externalid/{external_id}/users ?startIndex={startIndex}&count={count}&reduced=true
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Parámetros
- startindex = índice inicial para la paginación (Integer, opcional)
- count = total de elementos a recuperar para la paginación (Integer, opcional)
Campos devueltos en el Json
Listado de usuarios, cada usuario consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- username = Nombre de usuario
- firstName = Nombre
- lastName = Apellidos
- preferredLanguage = Idioma predeterminado
- personTimezoneId = Zona horaria
- roles = Roles del usuario
- email = Correo electrónico del usuario
- officePhoneNumber = Teléfono de oficina
- mobilePhoneNumber = Teléfono móvil
- address = Dirección
- jobTitle = Puesto
- location = Departamento
- organization = Compañía
- aboutMe = Sobre mí
- interests = Intereses
- status = Estado
- extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValue
Cuando se pasa el parámetro reduced=true los campos devueltos serán los siguientes:
- id = Identificador
- external_id = Id externo
- username = Nombre de usuario
- email = Correo electrónico del usuario
- status = Estado
Validaciones
- Índices erróneos --> Error 416 (Requested Range Not Satisfiable)
- Usando paginación, ambos índices deben tener un valor
- Si el grupo no existe --> Error 404 (Not Found)
- No hay usuarios --> Error 204 (No Content)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK
- Si no hay paginación --> 200 (OK) + JSON
- Si hay paginación --> 206 (Partial Content) + JSON
Eliminar usuarios de un grupo/subgrupo
Método: DELETE
URL:
- Eliminar por id:
- /admin/rest/administration/api/groups/id/{id}/users?action={action}
- Eliminar por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}/users?action={action}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/users?action=removeByUserIds
- Formulario:
- id=51476&id=654165&id=6566
Parámetros
- action = acción que se quiere realizar (borrar usando ids de usuarios o ids externos) (String, obligatorio)
- Valores permitidos
- removeByUserIds
- removeByUserExternalids
- Valores permitidos
- id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio) Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Campos devueltos en el Json (en caso de que algún usuario haya dado error)
- status: KO
- ids / external ids: listado de ids o external ids que han dado error
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
- Se ha escogido la acción "removedByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
- No existe el grupo --> Error 400 (Not Found)
- Ejecución OK y todos los usuarios han sido eliminados --> 200 (OK)
- Ejecución OK y algún usuario no ha podido ser eliminado --> 200 (OK) + JSON
Obtener administradores de grupo
Método: GET
URL:
- Obtener por id:
- /admin/rest/administration/api/groups/id/{id}/admins
- Obtener por external id:
- /admin/rest/administration/api/groups/externalid/{external_id}/admins
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Campos devueltos en el Json
Administrador, cada administrador consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- username = Nombre de usuario
- firstName = Nombre
- lastName = Apellidos
- preferredLanguage = Idioma predeterminado
- personTimezoneId = Zona horaria
- roles = Roles del usuario
- email = Correo electrónico del usuario
- officePhoneNumber = Teléfono de oficina
- mobilePhoneNumber = Teléfono móvil
- address = Dirección
- jobTitle = Puesto
- location = Departamento
- organization = Compañía
- aboutMe = Sobre mí
- interests = Intereses
- status = Estado
- extendedFields = Campos extensibles en lista con clave extendedFieldName y valor extendedFieldValues
- teamManagerUsername = Nombre de usuario del jefe de equipo
Validaciones
- No existe el grupo Error 404 (Not Found)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
Añadir administradores a un grupo/subgrupo
Método: POST
URL:
- Añadir por id:
- /admin/rest/administration/api/groups/id/{id}/admins?action={action}
- Añadir por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}/admins?action={action}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/admins?action=addByUserIds
- Body:
{
"ids": [51476,654165]
}
Parámetros
- action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
- Valores permitidos
- addByUserIds
- addByUserExternalids
- Valores permitidos
- id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Campos devueltos en el Json (en caso de que algún usuario haya dado error)
- status: KO
- ids / external ids: listado de ids o external ids que han dado error y los códigos de error
- GRP002: El usuario no existe
- GRP003: El usuario ya es administrador de grupo
- GRP005: El usuario no tiene rol de administrador de la formación.
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
- Se ha escogido la acción "addByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
- No existe el grupo --> Error 400 (Not Found)
- Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
- Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON
Eliminar administradores de un grupo/subgrupo
Método: DELETE
URL:
- Añadir por id:
- /admin/rest/administration/api/groups/id/{id}/admins?action={action}
- Añadir por id externo:
- /admin/rest/administration/api/groups/externalid/{external_id}/admins?action={action}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487/admins?action=deleteByUserIds
- Body:
{
"ids": [51476,654165]
}
Parámetros
- action = acción que se quiere realizar (añadir usando ids de usuarios o ids externos) (String, obligatorio)
- Valores permitidos
- deleteByUserIds
- deleteByUserExternalids
- Valores permitidos
- id (lista) = cada uno de los identificadores o identificadores externos (String, obligatorio)
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Campos devueltos en el Json (en caso de que algún usuario haya dado error)
- status: KO
- ids / external ids: listado de ids o external ids que han dado error y los códigos de error
- GRP002: El usuario no existe
- GRP006: El usuario no es administrador del grupo.
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- Acción no válida (no se comprueban mayúsculas/minúsculas) --> Error ERR002 / 400 (Bad Request)
- Se ha escogido la acción "deleteByUserIds" y algún id no es numérico --> Error ERR003 / 400 (Bad Request)
- No existe el grupo --> Error 400 (Not Found)
- Ejecución OK y todos los usuarios han sido añadidos--> 200 (OK)
- Ejecución OK y algún usuario no ha podido ser añadido --> 200 (OK) + JSON
