API

La versión inicial del API para facilitar la interacción con servicios móviles y otros portales fue creada para acceso de forma pública.

Se ofrecen los siguientes servicios:

• Listado de colegios inscritos en la plataforma.(GET)
• Obtener información del estudiante y el juego dado un token de juego y sesión(GET)
• Obtener información extendida de un estudiante(GET) SG-629
• Obtener configuración global de un juego dado el token de juego(GET)
• Almacenar datos en el datastore del estudiante y sesión(POST)
• Enviar notificación a la plataforma para publicar en el muro del estudiante(POST)

Esquema general de conexión

Todos los métodos para obtener datos son GET, cuando es un listado, este estará paginado cada 30 registros.

En el caso de los métodos que modifiquen datos dentro del sistema, se empleará POST, específicamente en el almacenamiento de datos en el datastore del estudiante, así mismo en la publicación del muro del estudiante dentro del colegio. Estamos empleando únicamente POST y GET y en el caso de actualización del datastore del usuario no estamos empleando PUT a pesar de la convención ampliamente difundida para simplificar el uso del API para los desarrolladores.

De forma predeterminada se emplea json para la transferencia de información.

El punto de entrada para acceder al API es https://sabios.librosylibros.co , puede como primera medida visitar el listado de colegios en https://sabios.librosylibros.co

Por lo tanto, por ejemplo, para obtener el listado de colegios, con un navegador se puede visitar https://sabios.librosylibros.co/api/colegio/ que mostrará algo parecido a

Para hacer pruebas, desde la línea de comandos con curl se puede verificar la respuesta del API con un comando como:

curl -H 'Accept: application/json; indent=4' https://sabios.librosylibros.co/api/colegio/

Que arrojaría algo de la forma::

{

“count”: 8, “next”: null, “previous”: null, “results”: [

{

“url”: “http://localhost:8500/api/colegio/1/”, “id”: 1, “name”: “La escuela de Dou00f1a Rita”, “logo”: “uploads/school/1/982ac16c-4e63-488c-9905-6ba3b9b325f1/cambridge.jpg”, “slogan”: “Si no Entiende, Hay Tabla!!!!!”, “short_name”: “donarita”, “phones”: “123123123,123123123123”, “website”: “”, “latlon”: “4.684133,-74.047573”, “city”: null, “calendar”: “A”, “classification”: “Pu00fablico”, “address”: “”, “slug”: “la-escuela-de-dona-rita”

}, {

“url”: “http://localhost:8500/api/colegio/5/”, “id”: 5, “name”: “Los Andes”, “logo”: “uploads/school_logo/escudoLosAndes.png”, “slogan”: “”, “short_name”: “Los Andes”, “phones”: “”, “website”: “”,

No se requiere autenticación para consultar el API y se ofrece únicamente datos que no vayan a afectar privacidad de los integrantes de la comunidad.

Visitar los detalles de cada elemento

Cada elemento del listado ofrece el id mediante el cual puede ver el detalle del mismo, por ejemplo, si quiere ver el listado de colegios, visitaría https://apps.co/api/colegio/, si por otra parte desea ir al detalle del colegio con id 50, debería visitar https://sabios.librosylibros.co/api/colegio/50/.

Paginación

Nuestro API está paginado, el paginado se hace de 30 elementos, como notará, en cada página le será mostrad el conteo de elementos, en enlace con la página y la página anterior en caso de que sea el caso.

Endpoints

A continuación los endpoints para la consulta del API:

GET

• https://sabios.librosylibros.co/api/colegio/
• https://sabios.librosylibros.co/api/colegio/<ID_COLEGIO>/
• https://sabios.librosylibros.co/api/gameconf/<SU_LLAVE>/
• https://sabios.librosylibros.co/api/gameinfo/<SU_LLAVE>/<SESION_JUEGO>/

POST

• https://sabios.librosylibros.co/api/store/<SU_LLAVE>/<SESION_JUEGO>/
• https://sabios.librosylibros.co/api/noti/<SU_LLAVE>/<SESION_JUEGO>/

Métodos

Instituciones

Puede obtener el listado de instituciones

Configuración global del juego

Dado el api KEY del juego, puede consultar la configuración global del juego

Información de sesión de usuario

Dado el api KEY del juego y la sesión, puede obtener la información del usuario, la configuración global del juego, información de niveles y de la instancia específica para el usuario.

Almacenamiento de datos para el usuario

Se ofrece un endpoint para que el juego pueda almacenar en la plataforma Sabios la información que le permita al juego hacer tracking de la información.

Envío de notificaciones al muro por parte del juego

Se ofrece un endpoint para que el juego pueda publicar sobre el muro del usuario notificaciones.

Las notificaciones serán de máximo 255 caracteres, puede colocar URLs o la información que considere pertinente para que aparezca en el muro del estudiante.

Consumo desde lenguajes de programación

A continuación ofrecemos la forma para interactuar con el API de Parque Sabios desde Python.

Python

Por simplicidad emplearemos la librería requests(https://pypi.python.org/pypi/requests)

Listado de colegios

Para obtener el listado de colegios:

result = requests.get('http://sabios.librosylibros.co/api/colegio/')
result.json()

Para ver el detalle del colegio con id 1:

result = requests.get('http://sabios.librosylibros.co/api/colegio/1/')
result.json()

Configuración de un juego

Para obtener la configuración del juego con api key 123:

result = requests.get('http://sabios.librosylibros.co/api/gameconf/123/')'
result.json()

Datos de sesión de usuario

Para obtener los datos de sesión del usuario con api key 123 y usuario 123:

result = requests.get('http://sabios.librosylibros.co/api/gameinfo/123/123/')
result.json()

Notificaciones a un usuario

Para obtener la cantidad de notificaciones que el juego con apikey 123 con el usuario 123:

result = requests.get('http://sabios.librosylibros.co/api/noti/123/123/')
result.json()

Para enviar una notificación del juego con api key 123 y sesión de usuario 123, la notificación tendrá el mensaje “hola mundo”:

result = requests.post(
    'http://sabios.librosylibros.co/api/noti/123/123/',
    {"message": "hola mundo"}
)
result.json()

Data Store del usuario

Para consultar los valores y llaves almacenados en el datastore de un usuario:

result = requests.get('http://sabios.librosylibros.co/api/store/123/123/')
result.json()

Para actualizar valores de los campos alias y score del datastore del usuario:

result = requests.post(
    'http://sabios.librosylibros.co/api/store/123/123/',
    {"alias": "superuser", "score": 300}
)
result.json()