Recursos
API #Soyvisual
#Soyvisual pone a disposición de todas las aplicaciones que lo soliciten su biblioteca de recursos a través de un API.
¿Qué es y para qué sirve el API?
La interfaz de programación de aplicaciones, o API (Application Programming Interface) es un conjunto de funciones que ofrece nuestro catálogo para ser utilizado por otro software como una capa de abstracción.
Este API permite que, cualquier desarrollador de software, app o aplicaciones web, pueda hacer consultas directamente y "al vuelo" sobre nuestra base de datos de fotografías y láminas, para así utilizar nuestros recursos en ella.
El API, a partir de una serie de variables establecidas (ver Instrucciones de uso), devuelve la búsqueda en formato JSON, un estándar que facilita su procesamiento en cualquier entorno de desarrollo.
Recursos disponibles a través del API
El API da acceso de modo independiente al catálogo de fotografías y al catálogo de láminas ilustradas, diseñados para estimular el desarrollo del lenguaje y ayudar a personas con necesidades a comprender el mundo y comunicarse. Más información sobre su uso pedagógico.
Quién puede utilizar el API
El acceso al API es autentificado. Eso implica que, cualquier desarrollador que esté interesado en integrar la búsqueda de nuestros recursos en su desarrollo, puede tener acceso a nuestro API, si cumple las condiciones de uso y realiza la solicitud tal y como se explica a continuación. Una vez aprobada la solicitud se le enviará un "token" para autentificar el acceso.
Licencia y condiciones de uso
Herramientas gratuitas
Los recursos que se ofrecen en el API #Soyvisual se publican bajo Licencia Creative Commons (BY-NC-SA), para conseguir así un repositorio de contenido libre que también pueda ser compartido por usuarios, autorizándose su uso siempre que se cite la fuente, autor, se compartan bajo la misma licencia, sin que por ello se obtenga beneficio alguno y no se haga un uso comercial de los mismos.
Cualquier obra derivada que se elabore a partir los recursos contenidos en el API #Soyvisual se debe distribuir con la misma licencia Creative Commons (BY-NC-SA), con la siguiente cita: “Las fotografías/ láminas ilustradas utilizados a partir del API #Soyvisual son parte de una obra colectiva propiedad de la Fundación Orange y han sido creados bajo licencia Creative Commons (BY-NC-SA)”. Más información sobre la política de uso.
Herramientas comerciales
Queda excluido del permiso citado anteriormente el uso de los recursos #Soyvisual dentro de cualquier producto o publicación con fines comerciales. En el caso de que se esté interesado en un uso comercial de los materiales ya indicados, requerirá de autorización previa, expresa y por escrito de la Fundación Orange, en el supuesto de que desee solicitarla puede remitir una descripción detallada de la explotación que se desea realizar al siguiente correo electrónico: fundacion.es@orange.com indicando en el Asunto "Solicitud de uso comercial" y facilitando un nombre y teléfono de contacto.
Solitar acceso al API
Si estás interesado en integrar el API #Soyvisual en tu herramienta, ponte en contacto con nosotros a través de la dirección de correo hola@soyvisual.org aportando la siguiente información:
- Nombre de aplicación.
- Empresa/ desarrollador.
- Contacto
- Descripción.
- Tipo de licencia que usa la aplicación.
- Valores dentro del mundo de la comunicación aumentativa y ayudas técnicas.
El equipo de #Soyvisual facilitará el "token" necesario para la autenticación.
El "token" proporcionado será personal e instransferible y no debe ser comunicado por ninguna vía a terceros. Cualquier publicación del código fuente de un desarrollo que incluya la consulta a nuestro API deberá eliminar el token e incluir un comentario que indique dónde se puede solicitar.
Instrucciones de uso del API
Consideraciones
El API usa la arquitectura REST, lo cual permite ofrecer el servicio de una manera estándar, comprensible y con URL’s orientadas a recursos. Al ser de “sólo lectura”, todas las peticiones son de tipo GET. El formato de respuesta es JSON, por ser uno de los más extendidos y de más fácil lectura.
Autentificación
Para autenticarte con el API necesitas enviarnos el token como parte de la cabecera de las peticiones, o como parámetro en la URL, en caso de que el cliente no admita el envío de cabeceras. En caso de que no esté incluída o sea errónea, será devuelto un código de error HTTP 400. En caso de que sea correcto, devolverá el código HTTP 200 y el resultado solicitado.
Así, pues, las opciones de autenticación son:
- Caso de autenticación por cabecera (método recomendado): La cabecera es ‘X-AUTH-TOKEN’.
- Caso de autenticación por parámetro en la URL (método no recomendado): El parámetro de URL es ‘token’.
Paginación
En todos los casos, la respuesta incluye una serie de cabeceras HTTP con información relativa a la paginación, si se necesita utilizar.
| Cabecera | Descripción |
|---|---|
| X-Pagination-CurrentPage | Página que se ha recibido. |
| X-Pagination-PageSize |
Número de elementos por página. |
| X-Pagination-TotalPages |
Número de páginas totales de resultados listado que se está pidiendo, después de aplicar filtros, si los hubiera. |
| X-Pagination-TotalElements |
Número de elementos totales del listado que se está pidiendo, después de aplicar filtros, si los hubiera. |
Endpoint Fotos
-
Descripción: Obtiene el listado de fotos.
Parámetros opcionales en la URL
| Nombre | Descripción |
|---|---|
| query | Cadena a buscar. |
| matching |
Tipo de coincidencia de la palabra a buscar en ‘query’, por defecto ‘start’.
|
| items_per_page |
Número de elementos por página, por defecto ‘10’. Los valores permitidos son:
|
| page |
Número de página que se quiere obtener, desde 0 a N - 1, siendo N el número de páginas existentes. Por defecto se solicita la primera página (‘0’). |
| sort_by |
Valor por el que se quiere ordenar los resultados. Por defecto date si no hay parámetro query, o score si hay parámetro query definido.
|
| sort_order |
Orden, por defecto ‘ASC’ si el parámetro ‘sort_by’ es ’title’ y ‘DESC’ si es ‘score’ o ‘date’.
|
Respuesta
[{
"id": "Identificador único del recurso",
"type": "En este caso siempre es Photo",
"title": "Nombre del recurso",
"image": {
"src": "Ruta de la imagen del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"thumbnail": {
"src": "Ruta de la miniatura del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"created": "Fecha de creación del recurso, en formato Y-m-d H:i:s",
"changed": "Fecha de actualización del recurso, en formato Y-m-d H:i:s",
"definition": "Descripción del recurso o de su palabra principal asociada",
"tags": "Listado de etiquetas asociadas al recurso, separadas por coma",
"authors": "Listado de autores del recurso, separados por coma"
}, …]
Endpoint Láminas
-
Descripción: Obtiene el listado de láminas.
Parámetros opcionales en la URL
| Nombre | Descripción |
|---|---|
| query | Cadena a buscar. |
| matching |
Tipo de coincidencia de la palabra a buscar en ‘query’, por defecto ‘start’.
|
| items_per_page |
Número de elementos por página, por defecto ‘10’. Los valores permitidos son:
|
| page |
Número de página que se quiere obtener, desde 0 a N - 1, siendo N el número de páginas existentes. Por defecto se solicita la primera página (‘0’). |
| sort_by |
Valor por el que se quiere ordenar los resultados. Por defecto date si no hay parámetro query, o score si hay parámetro query definido.
|
| sort_order |
Orden, por defecto ‘ASC’ si el parámetro ‘sort_by’ es ’title’ y ‘DESC’ si es ‘score’ o ‘date’.
|
Respuesta
[{
"id": "Identificador único del recurso",
"type": "En este caso siempre es Sheet",
"title": "Nombre del recurso",
"image": {
"src": "Ruta de la imagen del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"thumbnail": {
"src": "Ruta de la miniatura del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"created": "Fecha de creación del recurso, en formato Y-m-d H:i:s",
"changed": "Fecha de actualización del recurso, en formato Y-m-d H:i:s",
"definition": "Descripción del recurso o de su palabra principal asociada",
"tags": "Listado de etiquetas asociadas al recurso, separadas por coma",
"authors": "Listado de autores del recurso, separados por coma"
}, …]Endpoint Recursos
-
Descripción: Obtiene el listado completos de fotos y láminas.
Parámetros opcionales en la URL
| Nombre | Descripción |
|---|---|
| query | Cadena a buscar. |
| type |
Tipo de recurso, por defecto todos: fotos y láminas.
|
| matching |
Tipo de coincidencia de la palabra a buscar en ‘query’, por defecto ‘start’.
|
| items_per_page |
Número de elementos por página, por defecto ‘10’. Los valores permitidos son:
|
| page |
Número de página que se quiere obtener, desde 0 a N - 1, siendo N el número de páginas existentes. Por defecto se solicita la primera página (‘0’). |
| sort_by |
Valor por el que se quiere ordenar los resultados. Por defecto date si no hay parámetro query, o score si hay parámetro query definido.
|
| sort_order |
Orden, por defecto ‘ASC’ si el parámetro ‘sort_by’ es ’title’ y ‘DESC’ si es ‘score’ o ‘date’.
|
Respuesta
[{
"id": "Identificador único del recurso",
"type": "Photo si es una foto, o Sheet si es una lámina",
"title": "Nombre del recurso",
"image": {
"src": "Ruta de la imagen del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"thumbnail": {
"src": "Ruta de la miniatura del recurso",
"alt": "Texto alternativo de la imagen del recurso"
},
"created": "Fecha de creación del recurso, en formato Y-m-d H:i:s",
"changed": "Fecha de actualización del recurso, en formato Y-m-d H:i:s",
"definition": "Descripción del recurso o de su palabra principal asociada",
"tags": "Listado de etiquetas asociadas al recurso, separadas por coma",
"authors": "Listado de autores del recurso, separados por coma"
}, …]