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

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

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:

https://demo.central-lms.com/admin/rest/administration/api/groups/id/2

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:

https://demo.central-lms.com/admin/rest/administration/api/groups

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:

https://demo.central-lms.com/admin/rest/administration/api/groups/id/2564/subgroups

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:

https://demo.central-lms.com/admin/rest/administration/api/groups/id/5487

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
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
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:

https://demo.central-lms.com/admin/rest/administration/api/groups/id/345/users?startIndex=0&count=100

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
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:

https://demo.central-lms.com/admin/rest/administration/api/groups/id/2/admins

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
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
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