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

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

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}

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

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

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

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:

• https://demo.central-lms.com/admin/rest/administration/api/categories?startIndex=0&count=100&language=es

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

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}

Ejemplo:

• https://demo.central-lms.com/admin/rest/administration/api/categories/id/2?language=en

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

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}

Ejemplo:

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

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