API PÚBLICA
API PUBLICA
Introducción
OpenLibra dispone de un ligero servicio web con el que es posible acceder de forma remota a la mayoría de los datos de su catálogo bibliográfico.
Mediante una petición AJAX (Javascript), se puede establecer una conexión directa con el sistema y obtener resultados en tiempo real sobre la consulta. El sistema devuelve un objeto JSON con el que es sencillo trabajar directamente en Javascript o en otros lenguajes de servidor como PHP o Java.
Esta primera versión del API facilita la creación de clientes independientes para OpenLibra, como por ejemplo de escritorio, que permitan rastrear el catálogo en tiempo real en busca de novedades, crear notificaciones con las actualizaciones, clasificar y buscar libros según un criterio concreto o facilitar la lectura de documentos directamente online sin navegador.
Javascript / JSONP
El acceso a la información se realiza mediante una petición AJAX (Javascript) a los servidores de OpenLibra los cuales devuelven un objeto JSON con los datos encontrados.
Ya que por temas de seguridad, los servidores no permiten llamadas AJAX entre dominios diferentes, hay que utilizar el complemento JSONP. Esto quiere decir que, en el callback de la llamada AJAX, va añadida una función Javascript para manejar los datos devueltos. Con las actuales bibliotecas de tipo jQuery, la forma de acceso resulta muy sencilla.
Un ejemplo típico de petición utilizando la citada jQuery es el siguiente:
$.getJSON( 'https://www.etnassoft.com/api/v1/get/?id=589&callback=?', function ( results ) {
console.log( 'Search Result(s): ', results );
} );
La petición anterior buscará en cualquier caso el libro con el ID número 589 en la base de datos. El sistema devolverá un objeto JSON como el siguiente:
[
{
"ID":"589",
"title":"Dise\u00f1o \u00c1gil con TDD",
"author":"Carlos Bl\u00e9 Jurados y autores",
"content":"",
"content_short":"Dedicas una gran parte de tu tiempo de desarrollo...",
"publisher":"www.iExpertos.com",
"publisher_date":"2010",
"pages":"309",
"language":"spanish",
"url_details":"https:\/\/www.openlibra.com\/book\/diseno-agil-con-tdd\/",
"url_download":"https:\/\/books.openlibra.com\/packed\/",
"url_read_online":"https:\/\/books.openlibra.com\/pdf\/",
"cover":"https:\/\/books.openlibra.com\/covers\/2011\/04\/disenoAgilConTDD.jpg",
"thumbnail":"http://collection.openlibra.com.s3.amazonaws.com/covers/2011/04/disenoAgilConTDD-110x153.jpg",
"num_comments":"0",
"categories":[],
"tags":[]
}
]
Parámetros
- id
-
() El id del libro
?id=505
- Default:
null
- Default:
- book_title
-
() El título del libro
?book_title=javascript
?book_title="eloquent javascript"
NOTA: Si el título son varias palabras, debe entrecomillarlo.
- Default:
null
- Default:
- book_author
-
() El autor del libro
?book_author=paenza
?book_author="Adrian Paenza"
NOTA: Si el título son varias palabras, debe entrecomillarlo.
- Default:
null
- Default:
- publisher
-
() La editorial del libro
?publisher=UOC
?publisher="Green Tea Press"
NOTA: Si el título son varias palabras, debe entrecomillarlo.
- Default:
null
- Default:
- publisher_date
-
() La fecha de publicación del libro
?publisher_date=2011
- Default:
null
- Default:
- lang
-
() Lenguaje del libro
?lang=english
- Default:
all
- Default:
- keyword
-
() Palabra clave del libro
?keyword=java
NOTA: Para buscar varias palabras, se pueden concatenar utilizando el signo +
NOTA 2: Debido a las limitaciones de este parámetro, en caso de enviarse varias palabras concatenadas, la búsqueda es estricta y únicamente se devolverán aquellos resultados donde se encuentren estas palabras de forma consecutiva.
?keyword=javascript+avanzado
- Se buscan aquellos libros que contengan de forma estricta la cadena javascript avanzado.
- Default:
null
- book_title_index
-
() Búsqueda por índice-prefijo
?book_title_index=a,b
Este parámetro permite realizar búsquedas por prefijo dentro de los títulos del catálogo. Útil para crear índices.
NOTA: La principal diferencia con keyword es que este argumento requiere que la cadena a buscar se encuentre al inicio de cada título.
NOTA 2: En caso de buscarse varios índices, es interesante utilizar el parámetro order para obtener una lista de resultados ordenada.
NOTA 3: En caso de buscarse varios índices y estar el número de resultados acotado mediante num_items, solo se devuelven los primeros n items del conjunto completo encontrado, siendo n el número indicado en num_items.
Este parámetro acepta varios índices separados por comas, lo cual indica al sistema que tiene que buscar objetos que coincidan con cada criterio/prefijo:book_title_index=z
- Se buscan aquellos libros que únicamente comiencen por la letra 'z'.book_title_index=a,b
- Se buscan aquellos libros que comiencen por la letra 'a' y la letra 'b'.book_title_index=0,1,2,3,4,5,6,7,8,9
- Se buscan aquellos libros cuyo título comience por un número (entre el 0 y el 9).book_title_index=s,m&num_items=100&order=a_z
- Se buscan aquellos libros que comiencen por la letra 's' y la letra 'm'; se ordenan alfabéticamente y del conjunto total se devuelven los 100 primeros.
- Default:
null
- category
-
() Categoría del libro ()
?category=programacion
- Default:
all
- Default:
- category_id
-
() ID de categoría ()
?category_id=212
- Default:
null
- Default:
- subcategory
-
() Subcategorías del libro ()
?subcategory=subversion
- Default:
all
- Default:
- subcategory_id
-
() ID de subcategoría ()
?subcategory_id=211
- Default:
null
- Default:
- any_tags
-
() Etiquetas que puede contener el libro
?any_tags=[Google, SEO, SEM]
NOTA: Se buscarán aquellos libros que pertenezcan al menos a una etiqueta.
- Default:
null
- Default:
- results_range
-
() Paginación de los resultados.
Este parámetro permite obtener segmentos concretos dentro del conjunto de resultados encontrados, siendo especialmente útil para crear una paginación.?results_range=0,10
Este parámetro acepta dos argumentos siendo el segundo opcional. El primero indica a partir de qué objeto se envía el resultado encontrado, mientras que el segundo indica cuántos objetos se van a enviar:results_range=0,10
- Se envían los 10 primeros resultados encontrados (empezando desde el resultado 0).results_range=10,10
- Se envían los siguientes 10 resultados encontrados (se comienza desde el item 10).results_range=20,10
- Se envían los siguientes 10 resultados encontrados (comenzando desde el item 20).results_range=30&num_items=20
- Sintaxis alternativa: se envían los n siguientes resultados siendo n el número definido mediante el parámetro num_items (por defecto, 10).
- Default:
null
- criteria
-
() Criterio para crear una colección
El criterio puede ser:
most_viewed
- Los libros más vistosmost_commented
- Los libros más comentados
- Default:
null
- order
-
() Filtro para ordenar los resultados
Los filtros pueden ser:
a_z
- Ordenación alfabética normal (A-Z)z_a
- Ordenación alfabética inversa (Z-A)newest
- Ordenación cronológica (el más nuevo primero)oldest
- Ordenación cronológica (el más antiguo primero)
- Default:
newest
- since
-
() En catálogo de OpenLibra desde...
Las cadenas pueden ser:
today
- Libros incorporados en el día actuallast_week
- Libros incorporados durante la última semanalast_month
- Libros incorporados durante el último meslast_year
- Libros incorporados durante el último año
- Default:
none
- num_items
-
() Número de libros a mostrar
?num_items=25
- Default:
10
- Default:
- count_items
-
() Número items devueltos.
En lugar de devolver todos los detalles de una consulta, muestra el número total de objetos encontrados. Útil para habilitar una paginación de resultados o para testing.?count_items=true
- Default:
false
- Default:
- decode
-
() Normaliza la codificación.
Normalización de caracteres (UTF-8) a lo largo de todo el objeto de respuesta. Por defecto, y para mantener la retrocompatibilidad, el parámetro está desactivado.?decode=true
- Default:
false
- Default:
- json
-
() Normaliza el formato.
Este parámetro elimina los paréntesis propios del formato JSONP.?json=true
- Default:
false
- Default:
Métodos
Sí, estos métodos se han añadido a posteriori y no son muy elegantes. Para la próxima v2 de la API, prometemos una API REST en condiciones ;)
- get_categories
-
() Devuelve todas las categorías
?get_categories=all
- Default:
none
- Default:
- get_subcategories_by_category_ID
-
() Devuelve todas las subcategorías que pertenecen a un ID de categoría dado
?get_subcategories_by_category_ID=677
- Default:
none
- Default:
Ejemplos de uso
Recuperar un libro mediante su ID
https://www.etnassoft.com/api/v1/get/?id=589
Recuperar los libros más vistos de la categoria programación
https://www.etnassoft.com/api/v1/get/?category=libros_programacion&criteria=most_viewed
Recuperar los libros más recientes etiquetados como HTML, CSS o Javascript
https://www.etnassoft.com/api/v1/get/?any_tags=[html,css,javascript]&order=newest
Recuperar los libros que tengan en algún campo el término Javascript y se hayan publicado durante 2011
https://www.etnassoft.com/api/v1/get/?keyword=javascript&publisher_date=2011
Recuperar todos los libros escritos por Adrián Paenza
https://www.etnassoft.com/api/v1/get/?book_author=adrian_paenza
Cargando...