Navegación

API del Planeador

Si la llamada al método fue exitosa, el código HTTP de estado de respuesta es 200 (OK). Si se intenta acceder a alguna llamada que requiere autenticación, sin pasar las credenciales apropiadas, el código de error será 401 (Unauthorized). Si el objeto con el que se va a interactuar no existe, el código será 404 (Not Found). Si se presenta un error de la plataforma, el código de error será 500 (Internal Server Error).

Autenticación y autorización

Para autenticar los servicios se trabaja con un token de autenticación, este token tiene tiempo de expiración máximo de un día, para refrescar el token basta con refrescar la página que proyecta el iframe. Cada vez que se visita la página que tiene un iframe se refresca el token.

El token se envía como parámetro GET en cada una de las tres páginas que tienen los iframes, a saber, el recetador, el planeador para administrador de colegio y el planeador de asignatura curso para los docentes.

El token para el administrador de plataforma únicamente es válido para los usuarios que estén en el grupo Admin Planeador que a su vez debe tener el permiso de modificar receta.

A nivel de planeaciones de curso asignatura, el administrador de colegio tiene permiso para editar las planeaciones de todos los profesores y cada profesor puede editar únicamente sus planeaciones, es decir aquellos curso asignatura en los cuales sea profesor o profesor auxiliar.

Si el token no es válido se obtendrá un error 401(Unathorized), en caso de que intente a acceder vía el webservice a un recurso que no esté bajo su potestad, se arrojará un error 403(FORBIDDEN)

A continuación un ejemplo de cómo obtener el token una vez se haya visitado una página que genere un token

_images/tokenreceta.png

Códigos de error

Cuando el servicio ofrece una respuesta exitosa, retorna siempre en formato JSON o bien un elemento o un listado de elementos paginados en porciones de 30 elementos. En caso de Internal Server Error hay unos códigos que ofrecen explicación adicional del error.

A continuación se describen los códigos de error y los mensajes respectivos que pueden emitir los servicios en caso de que el código de estado sea 500.

  • NO_BOOK_ID: 1 No hay un libro con el id recibido
  • NO_VERSION: 2 La versión no está presente
  • MALFORMED_JSON: 3 Json mal formado
  • MISSING_JSON: 4 Hace falta el json
  • ONLY_POST_ALLOWED: 5 Solamente se acepta método post
  • NO_RECIPE_FOR_BOOK: 6 No hay receta publicada para este libro
  • VERSION_RANGE_ERROR: 8 La versión debe estar entre 0 y 32000
  • VERSION_FROM_RANGE_ERROR: 9 La versión debe estar entre 0 y 32000
  • NO_PLANNING_FOR_COURSE_SUBJECT: 11 No hay planeación publicada para el curso asignatura.

Las Recetas

Puede acceder al índice de los métodos expuestos para las recetas vía

https://sabios.librosylibros.co/api/recipe/

El planeador se constituye como una aplicación que consume servicios de lectura y escritura de la plataforma.

La página de entrada a la construcción de recetas es https://sabios.librosylibros.co/planeador/ allí se genera el token para quienes tienen permiso para hacer administración de las recetas.

Estructuras JSON

A continuación presentamos los datos que ofrece una receta

Receta

book_id : (entero)
identificador de la edición del libro
version : (entero de 0 a 32000)
versión de la receta
json_recipe : (json)
receta
is_published : (booleano)
indica si ha sido publicada o no la receta
modified_at : (timestamp)
indica cuándo fue actualizada por última vez la receta
from_version : (entero de 0 a 32000)
indica la versión de la que proviene
created_by : (email)
Correo electrónico de la persona que creó la versión

Libro

book_id : (entero)
identificador del libro
name : (cadena)
nombre del libro
area : (cadena)
nombre del área
tier : (cadena)
nombre del grado en la plataforma

Dado un libro, se puede crear recetas para el mismo, de ahora en adelante vamos a emplear como ejemplo el libro con id 42.

En los ejemplos posteriores, asumimos que ya obtuvo su token de autenticación y que es 857893dbd1b96439cb9486e8ae38dac824b5758d

Obtener libros - getBooks

El primer método disponible es el listado de libros disponible en la plataforma, para acceder al mismo se usa GET sobre https://sabios.librosylibros.co/api/recipe/book/ , tal servicio está paginado de a 30 elementos.

Al aplicar:

curl -X GET https://sabios.librosylibros.co/api/recipe/book/ -H 'Authorization: Token 8dbc084dabf43baf5f5a29cf1ea08134c57487f3'

Se obtendrá algo parecido a:

{"count": 15, "next": null, "previous": null, "results": [{"book_id": 42, "name": "ZOOM A LAS CIENCIAS SOCIALES 1", "area": "Ciencias Sociales"}, {"book_id": 41, "name": "ZOOM A LAS CIENCIAS SOCIALES 2", "area": "Ciencias Sociales"}, {"book_id": 40, "name": "ZOOM A LAS CIENCIAS SOCIALES 3", "area": "Ciencias Sociales"}, {"book_id": 39, "name": "ZOOM A LAS CIENCIAS SOCIALES 4", "area": "Ciencias Sociales"}, {"book_id": 32, "name": "ZOOM A LAS CIENCIAS SOCIALES 5", "area": "Ciencias Sociales"}, {"book_id": 48, "name": "ZOOM A LAS MATEM\u00c1TICAS 1", "area": "Matem\u00e1ticas"}, {"book_id": 49, "name": "ZOOM A LAS MATEM\u00c1TICAS 2", "area": "Matem\u00e1ticas"}, {"book_id": 50, "name": "ZOOM A LAS MATEM\u00c1TICAS 3", "area": "Matem\u00e1ticas"}, {"book_id": 51, "name": "ZOOM A LAS MATEM\u00c1TICAS 4", "area": "Matem\u00e1ticas"}, {"book_id": 52, "name": "ZOOM A LAS MATEM\u00c1TICAS 5", "area": "Matem\u00e1ticas"}, {"book_id": 43, "name": "ZOOM AL LENGUAJE 1", "area": "Lenguaje"}, {"book_id": 44, "name": "ZOOM AL LENGUAJE 2", "area": "Lenguaje"}, {"book_id": 45, "name": "ZOOM AL LENGUAJE 3", "area": "Lenguaje"}, {"book_id": 46, "name": "ZOOM AL LENGUAJE 4", "area": "Lenguaje"}, {"book_id": 47, "name": "ZOOM AL LENGUAJE 5", "area": "Lenguaje"}]}

Los libros en cada paginación serán un listado de estructuras Libro

Obtener la receta base - getBookStore

Para obtener la receta base del libro basta con acceder vía GET a https://sabios.librosylibros.co/api/recipe/42/base/ , puede emplear:

curl -X POST https://sabios.librosylibros.co/api/recipe/42/base/ -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d" -H "Content-Type: application/json"

El cual arrojará un json de receta marcado con la versión 0 y que proviene de la versión 0, parecido a:

{"book_id": 42, "version": 0, "json_recipe": "{\"estandares\": [{\"nucleos\": [{\"id_nucleo\": 165, \"texto_estrategia_lyl\": \"\", \"texto_nucleo_lyl\": \"ME ORIENTO\", \"texto_actividades_lyl\": \"\", \"temas\": [{\"texto_recursos_lyl\":...

Crear recetas para un libro - storeRecipe

Dado que ya tenemos la información básica para construir las recetas del libro, para añadir la versión 1 de la receta al libro, se usaría el método POST sobre https://sabios.librosylibros.co/api/recipe/42/1/ con una llamada como:

curl -X POST https://sabios.librosylibros.co/api/recipe/42/1/ -d '{"from_version": 0, "json_recipe": {}' -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d" -H "Content-Type: application/json"

Obtendrá una respuesta en formato JSON similar a lo siguiente:

{"book_id": 42, "version": 1, "json_recipe": "{}", "is_published": false, "modified_at": "2014-01-22 15:15:51", "from_version": 0, "created_by": "correo@correo.com.co"}

Es posible crear más versiones de la misma receta, por ejemplo, si se hace POST sobre https://sabios.librosylibros.co/api/recipe/42/2/ , será posible crear la versión 2 de la receta para el libro con id 42, por ejemplo:

curl -X POST https://sabios.librosylibros.co/api/recipe/42/2/ -d '{"from_version": 1, "json_recipe": {}' -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d" -H "Content-Type: application/json"

De nuevo obtendrá la receta de cómo quedó almacenada la información similar a:

{"book_id": 42, "version": 2, "json_recipe": "{}", "is_published": false, "modified_at": "2014-01-22 15:15:51", "from_version": 1, "created_by": "correo@correo.com.co"}

También puede modificar recetas, basta con usar el mismo una URL de una receta con una versión ya existente con POST, como por ejemplo:

curl -X POST https://sabios.librosylibros.co/api/recipe/42/2/ -d '{"json_recipe": "{\"list\": [1, 2]}", "from_version": 1}' -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d" -H "Content-Type: application/json"

Obtendrá una respuesta como:

{"book_id": 42, "version": "2", "json_recipe": "{u'list': [1, 2]}", "is_published": false, "modified_at": "2014-01-22 15:20:04", "from_version": 1, "created_by": "correo@correo.com.co"}

Cabe notar que el id del libro y la versión están en el URL, mientras que la versión de la que proviene y la receta en cuestión son datos que debe enviar, siempre que guarde o actualice una receta exitósamente obtendrá una estructura de receta.

Obtener una receta - getRecipe

Para obtener la versión de una receta previamente publicada basta con hacer GET sobre la versión del libro en cuestión, por ejemplo, para obtener la información de la versión 2 se emplearía:

curl https://sabios.librosylibros.co/api/recipe/42/2/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Obtendrá algo similar a:

{"book_id": 42, "version": 2, "json_recipe": "{\"list\": [1, 2]}", "is_published": false, "modified_at": "2014-01-22 15:20:04", "from_version": 1, "created_by": "correo@correo.com.co"}

La entrada es el id del libro y la versión, que van incluídas en la URL, se obtendrá en caso de éxito una estructura de receta.

Obtener las recetas de un libro - getRecipeVersions

Para obtener las recetas del libro, se accede con GET a https://sabios.librosylibros.co/api/recipe/42/list/ con una llamada como:

curl -X GET https://sabios.librosylibros.co/api/recipe/42/list/ -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d"

Obtendrá una respuesta en JSON similar a:

{"count": 2, "next": null, "previous": null, "results": [{"book_id": 42, "version": 1, "json_recipe": "{\"list\": [1, 2]}", "is_published": false, "modified_at": "2014-01-22 15:19:36", "from_version": 1, "created_by": "correo@correo.com.co"}, {"book_id": 42, "version": 2, "json_recipe": "{\"list\": [1, 2]}", "is_published": false, "modified_at": "2014-01-22 15:20:04", "from_version": 1, "created_by": "correo@correo.com.co"}]}

Tenga en cuenta que los resultados están paginados; cada petición entrega máximo 30 elementos. Las URLs correspondientes para pedir las páginas anterior o siguiente se entregan en la respuesta, en los atributos previous y next de la respuesta.

Por ejemplo, para acceder a la página 32 agregará el parámetro GET page

La entrada es el id del libro que va en la URL y el resultado es un json que contiene la cantidad total de recetas para el libro, la página anterior, la página siguiente y los resultados de la página actual en una lista de recetas.

Publicar una receta - setPublicRecipe

Dado que es posible tener muchas versiones, habrá una única versión para que los colegios puedan tomarla para hacer sus planeaciones. En este caso si se desea publicar la versión 2, se empleará el método POST sobre https://sabios.librosylibros.co/api/recipe/42/1/publish/ con una llamada como:

curl -X POST https://sabios.librosylibros.co/api/recipe/42/1/publish/ -H "Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d"  -H "Content-Type: application/json"

Obtendrá una respuesta en formato JSON como:

{"book_id": 42, "version": 1, "json_recipe": "{\"list\": [1, 2]}", "is_published": true, "modified_at": "2014-01-22 15:19:36", "from_version": 1, "created_by": "correo@correo.com.co"}

Esta acción establecerá la versión indicada como la pública.

La entrada es el id del libro y la versión de la receta a publicar, estas vienen en el URL y como resultado de forma exitosa se obtendrá una estructura de receta.

Obtener la receta publicada - getPublishedRecipe

Una vez que hay una receta publicada se puede acceder a https://sabios.librosylibros.co/api/recipe/42/ con el método GET con una llamada como:

curl -X GET https://sabios.librosylibros.co/api/recipe/42/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'  -H "Content-Type: application/json"

Obtendrá la receta de la versión pública para el libro en formato json:

{"book_id": 42, "version": 1, "json_recipe": "{\"list\": [1, 2]}", "is_published": true, "modified_at": "2014-01-22 15:19:36", "from_version": 1, "created_by": "correo@correo.com.co"}

Si el llamado es de un libro válido se obtiene una estructura de la receta publicada.

El Planeador

Puede acceder al índice de los métodos expuestos para el planeador vía

https://sabios.librosylibros.co/api/planning/

El administrador de colegio puede acceder al planeador de cada asignatura vía el menú planeador cuando está administrando un curso, en esa página se regenerará el token cada vez que la visite

_images/menuplaneadoradmin.png

Por su parte el profesor de colegio puede acceder al planeador de cada asignatura vía el menú que aparece en cada curso asignatura que tenga asignado, allí se regenerará el token

_images/editar-plan-anual.png

Para efectos prácticos, los ejemplos a continuación asumen que el token es 8dbc084dabf43baf5f5a29cf1ea08134c57487f3 , el colegio tiene identificador 1.

Estructuras JSON

Plan

course_subject_id : (entero)
identificador del cursoasignatura
version : (entero de 0 a 32000)
versión del plan
json_planing : (json)
planeación
is_published : (booleano)
indica si ha sido publicada o no la receta
modified_at : (timestamp)
indica cuándo fue actualizada por última vez la receta
from_version : (entero de 0 a 32000)
indica la versión de la que proviene
teacher_name : (cadena)
nombre del profesor del curso asignatura
subject_name : (cadena)
nombre del área
course_name : (cadena)
nombre del curso
tier_name : (cadena)
nombre del grado en la plataforma
book_name : (cadena)
nombre del libro
book_id : (entero)
id de la edición del libro
created_by : (email)
Correo electrónico de la persona que creó la versión

Resumen de planeación

course_subject_id : (entero)
identificador del cursoasignatura
plan_version : (entero de 0 a 32000)
versión del plan
teacher_name : (cadena)
nombre de quien creó el plan
subject_name : (cadena)
nombre de la asignatura
course_name : (cadena)
nombre del curso
tier_name : (cadena)
nombre del grado en la plataforma
modified_at : (timestamp)
indica cuándo fue actualizada por última vez la receta
created_by : (email)
Correo electrónico de la persona que creó el plan

Curso Asignatura

name : (cadena)
nombre de curso asignatura
teacher_name : (cadena)
nombre del profesor del curso asignatura
subject_name : (cadena)
nombre del área
book_name : (cadena)
nombre del libro
tier_name : (cadena)
nombre del grado
course_name : (cadena)
nombre del curso
section_name : (cadena)
nombre del ciclo

Obtener columnas de planeación - getColumns

Para obtener las columnas de planeación del colegio con id 1, se visita https://sabios.librosylibros.co/api/planning/columns/1/

Al aplicar:

curl https://sabios.librosylibros.co/api/planning/columns/1/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Se obtiene una lista de resultados con estructura JSON sin paginación:

[{"id": 5, "name": "Cuestionate", "description": "Pregunta general del proyecto", "position": 1}, {"id": 6, "name": "Reflexiona", "description": "Reflexi\u00f3n del proyecto", "position": 2}]

Adicionar o editar una planeación - storePlan

Para añadir una planeación al curso asignatura con id 42, con la versión 1, se aplicaría:

curl -X POST https://sabios.librosylibros.co/api/planning/42/1/ -d '{"json_planning": "{}"}' -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d' -H "Content-Type: application/json"

Obtendrá una estructura de Planeación en JSON parecida a:

{"course_subject_id": 42, "version": 1, "json_planning": "{}", "is_published": true, "modified_at": "2014-01-23 14:54:32", "from_version": 0, "created_by": "lunadj12@gmail.com"}

La edición de la versión se hace exactamente con el mismo comando con un curso asignatura y una versión ya existente:

curl -X POST https://sabios.librosylibros.co/api/planning/42/1/ -d '{"json_planning": "{}"}' -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d' -H "Content-Type: application/json"

Los parámetros admitidos son:

  • json_planning: cadena de texto con información json incluída(JSON Obligatorio)
  • from_version: versión de la cual proviene, 0 si es la primera(entero)

Versión de planeación - getPlan

Para obtener la versión 1 de planeación dado el id de un libro con id 42 se puede visitar https://sabios.librosylibros.co/api/planning/42/1/

En esta oportunidad se emplea el método GET, por ejemplo:

curl https://sabios.librosylibros.co/api/planning/42/1/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Que entregaría una estructura de datos JSON de planeación parecida a:

{"course_subject_id": 42, "version": 1, "json_planning": "{}", "is_published": false, "modified_at": "2014-01-23 14:54:32", "from_version": 0, "created_by": "lunadj12@gmail.com"}

Listado de versiones de planeación - getPlanVersions

Para obtener el listado de todas las versiones para una asignatura curso con id 42 se puede emplear:

curl https://sabios.librosylibros.co/api/planning/42/list/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Obtendrá un listado de estructuras de planeación parecido a:

{"count": 1, "next": null, "previous": null, "results": [{"course_subject_id": 42, "version": 1, "json_planning": "{}", "is_published": true, "modified_at": "2014-01-23 14:54:32", "from_version": 0, "created_by": "lunadj12@gmail.com"}]}

Con la paginación usual.

Pubicar una versión de planeación - setPublicPlan

Para publicar la versión 1 de planeación del curso asignatura con id 42, se puede aplicar:

curl -X POST https://sabios.librosylibros.co/api/planning/42/1/publish/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Obtendrá una estructura de planeación json parecida a:

{"course_subject_id": 42, "version": 1, "json_planning": "{}", "is_published": true, "modified_at": "2014-01-23 14:54:32", "from_version": 0, "created_by": "lunadj12@gmail.com"}

Obtener la versión publicada de un plan de asignaturacurso - getPublishedPlan

Para obtener el plan publicado para una asignatura curso con id 42 con curl se aplicaría:

curl https://sabios.librosylibros.co/api/planning/42/ -H 'Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d'

Obtendrá una estructura de planeación parecida a:

{"course_subject_id": 42, "version": 1, "json_planning": "{}", "is_published": true, "modified_at": "2014-01-23 14:54:32", "from_version": 0, "created_by": "lunadj12@gmail.com"}

Obtener todos los planes publicados de un curso - getCoursePlan

Para obtener los planes publicados para un curso con id 29 con curl se aplicaría

curl https://sabios.librosylibros.co/api/planning/course/29/ -H ‘Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d’

Obtendrá un listado de estructuras de curso asignatura parecido a:

{"count": 1, "next": null, "previous": null, "results": [{"course_subject_id": 48, "teacher_name": "Diana Ariza", "subject_name": "Ciencias Sociales", "plan_version": 1, "modified_at": "2014-01-23 14:54:32", "created_by": "lunadj12@gmail.com"}]}

Obtener información de un Curso asignatura - getCourseSubjectInfo

Para obtener los planes publicados para un curso asignatura con id 42 con curl se aplicaría

curl https://sabios.librosylibros.co/api/planning/course_subject_data/42/ -H ‘Authorization: Token 857893dbd1b96439cb9486e8ae38dac824b5758d’

Obtendrá un listado de estructuras de curso asignatura parecido a:

{"course_subject_id": 42, "teacher_name": "Diana Ariza", "subject_name": "Ciencias Sociales", "plan_version": 1, "modified_at": "2014-01-23 14:54:32", "created_by": "lunadj12@gmail.com"}

Configuración de URLS base de los clientes

Cada uno de las interfaces de planeador: frontend de administrador de plataforma para recetas, planeador para administrador de colegio y planeador para profesor son configurables vía https://sabios.librosylibros.co/admin/constance/config/ a través de las variables URL_BASE_PLANNER_ADMIN, URL_BASE_PLANNER_SCHOOL_ADMIN y URL_BASE_PLANNER_TEACHER.

El planeador de recetas cuenta con el parámetro GET en la llamada al iframe:

  • token Token del usuario para consumir servicios

El planeador de administrador de colegio cuenta con los parámetros GET en la llamada al iframe:

  • token Token del usuario para consumir servicios
  • id_curso Id del curso
  • id_school Id del colegio

El planeador del profesor cuenta con los parámetros GET en la llamada al iframe:

  • token Token del usuario para consumir ser
  • id_curso Id del curso
  • id_coursesubject Id de curso asignatura
  • id_book Id del libro, es opcional
  • id_school Id del colegio

Contenidos

Tema anterior

API de Sabiatón

Próximo tema

API del Tutor

Esta página

Navegación

© Copyright 2013, Libros y Libros S.A. Creado con Sphinx 1.1.3.