Esta publicación en español, está basada en las publicaciones en inglés realizadas por Isaac y Shayn anteriormente.
Para empezar, una REST API es un programa informático que permite que dos aplicaciones se puedan comunicar entre sí, por ejemplo, una API es la que permite que nuestros teléfonos puedan consultar los datos del tráfico que están almacenados en grandes servidores. En el caso de la REST API de Crossref, una aplicación (un manejador de referencias, un script que recupera metadatos, o nuestra computadora personal) se comunica con nuestros servidores y recupera metadatos académicos. La manera como se interactúa con una REST API es a través de consultas que se ejecutan directamente en un navegador de internet con una URL (ejemplo: https://api.crossref.org/prefixes/10.35195/works), usando un cliente de API como Postman o mediante otros programas informáticos o scripts.
En el caso de Crossref, hay 3 formas de acceder a nuestra API:
- De forma anónima (Public API REST)
- Identificando el usuario que realiza la consulta (Polite API REST)
- Con autenticación (Plus API REST)
En cualquiera de los tres casos, los resultados son los mismos, sin embargo nuestra recomendación es agregar siempre la identificación del usuario que realiza la consulta (Polite API REST), así podemos comunicarnos con la persona que está ejecutando las consultas en caso de que los scripts usados por los programadores estén causando problemas en el sistema. Esta identificación se logra agregando el parámetro “mailto=” en su consulta, ejemplo:
https://api.crossref.org/prefixes/10.35195/works?mailto=john.doe@mail.com
Aquí puede encontrar otras recomendaciones y buenas prácticas para hacer uso de nuestra API REST. También hemos creado una sección donde puede consultar tutoriales con diferentes herramientas para aprender desde cero a realizar consultas a nuestra REST API.
Veamos algunos ejemplos de consultas accediendo a nuestra API de forma anónima (mostrados en la columna Consulta - API Query) o polite (demostración usando Postman):
1. Endpoint: works
Ejemplos de consultas que exponen datos sobre ítems específicos (works):
| Pregunta en lenguaje natural | Consulta - API Query |
|---|---|
| 1.1. ¿Cuáles son los metadatos registrados para el DOI 10.7705/biomedica.7469? | https://api.crossref.org/works/10.7705/biomedica.7469 |
| 1.2. ¿Qué ítems del autor identificado con el ORCID 0000-0002-9117-4510 están registrados en Crossref ? | https://api.crossref.org/works?filter=orcid:0000-0002-9117-4510 |
| 1.3.¿Cuántos DOI se han registrado para el prefijo 10.25145 durante el año 2024?, detallar por tipo documental (informes, congresos, libros, artículos de revistas, …) | https://api.crossref.org/prefixes/10.25145/works?facet=type-name:*&filter=from-created-date:2024-01-01,until-created-date:2024-12-31&rows=0 |
Notas:
1.2. Se pueden agregar filtros filter= a las consultas para tener resultados más específicos.
1.3. Al agregar el parámetro facet= se tendrá un resumen del total de registros que cuentan con cierta categoría y sus respectivos valores
El parámetro rows=0 muestra el total de resultados de la consulta y hace que la búsqueda sea más eficiente. Esto es útil cuando solamente se quieren saber totales y no el detalle de los resultados.
Demostración usando Postman:
2. Endpoint: prefixes
Ejemplos de consultas que exponen datos relacionados con un prefijo.
| Pregunta en lenguaje natural | Consulta (API Query) |
|---|---|
| 2.1. ¿Cuáles DOI han sido registrados asociados al prefijo 10.62169? | https://api.crossref.org/prefixes/10.62169/works |
| 2.2. ¿Cuáles son los títulos de los DOI que han sido registrados asociados al prefijo 10.7705? | https://api.crossref.org/prefixes/10.7705/works?select=DOI,title |
| 2.3. ¿Cuáles DOI asociados al prefijo 10.22430 se han registrado incluyendo la licencia bajo la cual se distribuyen sus contenidos? | https://api.crossref.org/prefixes/10.22430/works?filter=has-license:true&rows=100 |
Notas:
2.2. Se puede agregar el parámetro select= para recuperar únicamente los campos seleccionados y hacer las consultas más eficientes, en este caso los campos “DOI” y “title”.
2.3. El parámetro rows=100 muestra solamente los primeros 100 resultados
Demostración usando Postman:
3. Endpoint: members
Ejemplos de consultas que exponen datos relacionados con la membresía a crossref:
| Pregunta en lenguaje natural | Consulta (API Query) |
|---|---|
| 3.1. ¿Qué instituciones que tengan en su nombre la palabra “ministerio” son miembros de Crossref? | https://api.crossref.org/members?query=ministerio |
| 3.2. ¿Cuántos y cuáles son los DOI registrados por la Universidad Nacional Autónoma de México? | https://api.crossref.org/members/9467/works |
| 3.3.¿Cuáles de los DOI anteriores corresponden a artículos de revista? | https://api.crossref.org/members/9467/works?filter=type:journal-article |
Notas
3.1. El parámetro query= permite realizar búsquedas libres de texto
3.3. El parámetro filter= se usa para recuperar solamente un conjunto de los ítems que cumplan con cierto criterio, en este caso aquellos que son del tipo “journal-article” type:journal-article
Demostración usando Postman:
4. Endpoint: journals
Ejemplos de consultas que exponen datos relacionados con las revistas (journals):
| Pregunta en lenguaje natural | Consulta (API Query) |
|---|---|
| 4.1. ¿Cuáles son los DOI asociados a la revista con ISSN 2323-0118? | https://api.crossref.org/journals/2323-0118/works |
| 4.2. De los ítems anteriores, muéstreme el título, volumen, número y páginas (primeros 20 resultados): | https://api.crossref.org/journals/2323-0118/works?select=DOI,title,volume,issue,page |
| 4.3. De los ítems anteriores, muéstreme el título, volumen, número y páginas (primeros 500 resultados): | https://api.crossref.org/journals/2323-0118/works?select=DOI,title,volume,issue,page&rows=500 |
Notas:
4.2. Por defecto la API de Crossref muestra los primeros 20 resultados.
4.3. El parámetro rows=500 aumenta la cantidad de resultados a 500
Demostración usando Postman:
5. Endpoint: funders
Ejemplos de consultas que exponen datos sobre financiadores (funders):
| Pregunta en lenguaje natural | Consulta (API Query) |
|---|---|
| 5.1. ¿Qué financiadores de Ecuador tienen registros en Crossref? | http://api.crossref.org/funders?filter=location:Ecuador |
| 5.2. ¿Cuáles DOI han registrado el “Ministerio del Ambiente, Agua y Transición Ecológica” como financiador de investigación? | https://api.crossref.org/funders/100019129/works |
| 5.3. Usando los mismos datos de la pregunta anterior, muéstreme todos los registros ordenados por las citaciones que han recibido, en forma descendente | https://api.crossref.org/funders/100019129/works?sort=is-referenced-by-count&rows=40&order=desc |
Notas:
5.3. Se agregaron los parámetros sort=is-referenced-by-count (ordenado según la cantidad de citaciones que ha tenido cada registro), rows=40 (muestra los primeros 40 ítems), order=desc (muestra los resultados en orden descendente)
Demostración usando Postman:
6. Endpoint: types
Ejemplos de consultas que exponen datos sobre tipos de documentos:
| Pregunta en lenguaje natural | Consulta (API Query) |
|---|---|
| 6.1.¿Cuáles son los tipos de documentos registrados en Crossref? | https://api.crossref.org/types |
| 6.2. ¿Cuántos capítulos de libros publicados en enero de 2025 han sido registrados? | https://api.crossref.org/types/book-chapter/works?filter=from-pub-date:2025-01-01,until-pub-date:2025-01-31&rows=0 |
| 6.3. ¿Cuáles son los 20 financiadores de subvenciones (grants) más recurrentes? | https://api.crossref.org/types/grant/works?facet=funder-name:*rows=20 |
Demostración usando Postman:
¿Tiene alguna pregunta que considere se puede contestar usando una consulta en nuestra API?
¿Desea compartir alguna consulta API que actualmente esté usando y que no esté listada en los ejemplos anteriores?
¿Tiene dudas adicionales sobre el uso de nuestra REST API?
¡Todos los comentarios son bienvenidos!