API Categorías
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 categoría
Método: POST
URL: /admin/rest/administration/api/categories
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/categories
- Formulario:
- external_id=exg1&name=Categoria1&code=CAT-1&description=Descripción de categoria1&i18n[es]=Categoría&i18n[en]=Category
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 de la categoría (String, obligatorio)
- code = Código de la categoría (String, opcional)
- Sólo puede contener letras, números y guiones (_ o -)
- Si no se cubre este campo, se creará un código por defecto con el formato CAT-<id-categoría>
- description = Descripción de la categoría (String, opcional)
- i18n[clave idioma] (lista) = Internacionalización de la categoría (clave-valor de Strings, opcional)
- Valores permitidos para "clave idioma" = los idiomas de la plataforma:
- en = Inglés, es = Español, pt = Portugués, it = Italiano, gl = Gallego,...
- Valores permitidos para "clave idioma" = los idiomas de la plataforma:
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir--> Error ERR001 / 400 (Bad Request)
- El nombre de categoría ya existe --> Error CTG001 / 400 (Bad Request)
- El id externo de categoría ya existe --> Error ERR006 / 400 (Bad Request)
- El identificador del idioma no existe --> Error CTG003 / 400 (Bad Request)
- El código de categoría ya existe --> Error CTG004 / 400 (Bad Request)
- El formato del código no es válido --> Error CTG005 / 400 (Bad Request)
Respuesta OK
- 201 (Created) + cabecera 'Location' con el link al recurso creado
Modificar categoría (sin internacionalización)
Método: PUT
URL:
- Modificar por id:
- /admin/rest/administration/api/categories/id/{id}
- Modificar por id externo:
- /admin/rest/administration/api/categoriesexternalid/{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/categories/id/1
- Formulario:
- external_id=ctg1&name=Category1&code=CAT-1x&description=Category description 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 (String, obligatorio)
- code = Código de la categoría (String, opcional)
- Sólo puede contener letras, números y guiones (_ o -)
- Si no se cubre este campo, se creará un código por defecto con el formato CAT-<id-categoría>
- description = Descripción del grupo (String, opcional)
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir --> Error ERR001 / 400 (Bad Request)
- No existe la categoría --> Error 404 (Not Found)
- El nombre de categoría ya existe --> Error CTG001 / 400 (Bad Request)
- El código de categoría ya existe --> Error CTG004 / 400 (Bad Request)
- El formato del código no es válido --> Error CTG005 / 400 (Bad Request)
- El id externo de categoría ya existe --> Error ERR006 / 400 (Bad Request)
- Todo OK --> 200 (OK)
Crear/Modificar internacionalización (todos los idiomas)
Método: PUT
URL:
- Modificar por id:
- /admin/rest/administration/api/categories/id/{id}/i18n
- Modificar por id externo:
- /admin/rest/administration/api/categoriesexternalid/{external_id}/i18n
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/categories/id/1/i18n
- Formulario:
- es=Categoría&en=Category
Parámetros
- clave idioma (lista) = Internacionalización de la categoría (clave-valor de Strings, obligatorio)
- Valores permitidos para "clave idioma" = los idiomas de la plataforma:
- en = Inglés, es = Español, pt = Portugués, it = Italiano, gl = Gallego,...
- Los valores que no se incluyan se inicializarán a nulo
- Valores permitidos para "clave idioma" = los idiomas de la plataforma:
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir --> Error ERR001 / 400 (Bad Request)
- No existe la categoría --> Error 404 (Not Found)
- Algún identificador de idioma no existe --> Error CTG003 / 400 (Bad Request)
- Todo OK --> 200 (OK)
Crear/Modificar internacionalización (un idioma)
Método: PUT
URL:
- Modificar por id:
- /admin/rest/administration/api/categories/id/{id}/i18n/{languageCode}
- Modificar por id externo:
- /admin/rest/administration/api/categoriesexternalid/{external_id}/i18n/{languageCode}
Ejemplo:
- https://demo.central-lms.com/admin/rest/administration/api/categories/id/1/i18n/es
- Formulario:
- value=Categoría
Parámetros
- value = Internacionalización de la categoría (String, obligatorio)
- Valores permitidos = los idiomas de la plataforma:
- en = Inglés, es = Español, pt = Portugués, it = Italiano, gl = Gallego,...
- Valores permitidos = los idiomas de la plataforma:
Validaciones
- Lista de parámetros vacía o algún campo obligatorio sin cubrir --> Error ERR001 / 400 (Bad Request)
- No existe la categoría --> Error 404 (Not Found)
- El identificador de idioma no existe --> Error CTG003 / 400 (Bad Request)
- Todo OK --> 200 (OK)
Obtener todas las categorías
Método: GET
URL:
- Obtener todas las categorías sin paginación:
- /admin/rest/administration/api/categories?language={languageCode}
- Obtener todas las categorías con paginación:
- /admin/rest/administration/api/categories?startIndex={startIndex}&count={count}&language={languageCode}
Ejemplo:
Parámetros
- startindex = índice inicial para la paginación (Integer, opcional)
- count = total de elementos a recuperar para la paginación (Integer, opcional)
- language = Idioma en el que se debe mostrar la categoría (String, opcional)
- Valores permitidos = los idiomas de la plataforma:
- all = Todos los idiomas, en = Inglés, es = Español, pt = Portugués, it = Italiano, gl = Gallego, all = todos...
- Valores permitidos = los idiomas de la plataforma:
Campos devueltos en el Json
Listado de categorías, cada categoría consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- name = Nombre de categoría
- code = Código de la categoría
- description = Descripción de categoría
Si se ha solicitado internacionalización, se mostrará un listado de parejas locale-name de la siguiente manera: - internacionalization
- locale = identificador del idioma
- name = valor internacionalizado (en caso de no estar cubierto, será null)
Validaciones
- Índices erróneos --> Error 416 (Requested Range Not Satisfiable)
- Usando paginación, ambos índices deben tener un valor
- No hay categorías--> Error 204 (No Content)
- El identificador del idioma no existe --> Error CTG003 / 400 (Bad Request)
- 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
Obtener categoría
Método: GET
URL:
- Obtener por id:
- /admin/rest/administration/api/categories/id/{id}?language={languageCode}
- Obtener por external id:
- /admin/rest/administration/api/categories/externalid/{external_id}?language={languageCode}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Parámetros
- idiom = Idioma en el que se debe mostrar la categoría (String, opcional)
- Valores permitidos = los idiomas de la plataforma:
- all = Todos los idiomas, en = Inglés, es = Español, pt = Portugués, it = Italiano, gl = Gallego, all = todos...
- Valores permitidos = los idiomas de la plataforma:
Campos devueltos en el Json
Categoría, cada grupo consta de los siguientes campos:
- id = Identificador
- external_id = Id externo
- name = Nombre de categoría
- code = Código de la categoría
- description = Descripción de categoría
Si se ha solicitado internacionalización, se mostrará un listado de parejas locale-name de la siguiente manera: - internacionalization
- locale = identificador del idioma
- name = valor internacionalizado (en caso de no estar cubierto, será null)
Validaciones
- El nombre de categoría por Id no existe --> Error ERR004 / 404 (Not Found)
- El nombre de categoría por External Id no existe --> Error ERR005 / 404 (Not Found)
- El identificador del idioma no existe --> Error CTG003 / 400 (Bad Request)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
Eliminar categoría
Método: DELETE
URL:
- Obtener por id:
- /admin/rest/administration/api/categories/id/{id}
- Obtener por external id:
- /admin/rest/administration/api/categories/externalid/{external_id}
Recuerda que por motivos de seguridad, el external_id no puede contener los caracteres \ ni /
Ejemplo:
Validaciones
- La categoría no existe --> 404 (Not Found)
- La categoría tiene actividades --> Error CTG002 / Error 400 (Bad Request)
- Error en la generación del Json --> Error 503 (Service Unavailable)
- Todo OK --> 200 (OK) + JSON
