Servicios web para el Registro del Portal de Datos
Puede encontrarse más información en el proyecto de wiki, y, en particular en la documentación de Servicios de la colección .
Servicios de datos
El registro del Portal de Datos de GBIF.ES sostiene los metadatos que describen:
- colecciones - colecciones de historia natural;
- instituciones - instituciones y organizaciones que gestionan las colecciones;
- PublicadoresDeDatos - proveedores de información sobre biodiversidad en forma electrónica, por ejemplo registros de observaciones o especímenes, sitios web;
- juegosDeDatos - recursos específicos puestos a disposición por los publicadores de datos;
- JuegosDeDatosTemporales - recursos temporales que contienen registros subidos al entorno de pruebas;
- CentrosDeDatos - agregadores de datos sobre biodiversidad; y
- contactos - para cualquiera de los recursos anteriores .
El acceso a estos metadatos es proporcionado por servicios web orientados a recursos se adhieren a RESTful principios. Los "payloads" de las respuestas están generalmente formateados como JSON Aunque algunos servicios ofrecen otros formatos a través de la negociación de contenido.
Los detalles de cómo se pueden utilizar estos servicios son proporcionados en el proyecto de wiki, y, en particular aquí.
Formulario de URIs
Todos los servicios de URIs se basan en la URI de esta página: | https://collections.ala.org.au/ws |
Los URIs de los recursos enumerados abajo están compuestos por esta raíz más el nombre del tipo de recurso, por ejemplo: | https://collections.ala.org.au/ws/institution |
El URI para una instancia específica de un recurso es el mismo seguido por el UID de la instancia. Por ejemplo, el recurso que representa el Aust. Wine Research Institute (UID = in72) es: | https://collections.ala.org.au/ws/institution/in72 |
El URI para obtener el recuento total de un recurso específico es el nombre del recurso seguido por 'count'. Por ejemplo, el número de instituciones se da por: | https://collections.ala.org.au/ws/institution/count |
Los recuentos para un recurso específico se pueden agrupar por cualquier atributo del recurso. Por ejemplo, el desglose de las instituciones por provincias viene dado por: | https://collections.ala.org.au/ws/institution/count/state |
Las fuentes que son atributos de un recurso, tales como la lista de contactos de una colección, se abordan anexando el tipo de recurso al uri que representa el recurso principal, por ejemplo: | https://collections.ala.org.au/ws/institution/in72/contacts |
Métodos
Los servicios de datos se apoyan en los métodos GET, HEAD, POST, PUT, OPTIONS y DELETE.
GET devolverá la representación 'json' del recurso especificado o la lista de todos los recursos del tipo de recurso especificado.
HEAD no devolverá ningún contenido pero confirmará la existencia del recurso especificado.
POST se actualizará el recurso especificado en función de la información del cuerpo de la solicitud. Si no se especifica un recurso, la información en el cuerpo se usará para crear un nuevo recurso. El cuerpo debe ser un 'json' válido y usted debe especificar al menos estas propiedades:
- usuario - el nombre de la aplicación que está solicitando la actualización; y
- api_key - una clave válida para verificar que está autorizado para modificar el recurso.
Si se está creando un nuevo recurso debe especificar al menos:
- nombre - el nombre del recurso
Otras propiedades son tratadas como las propiedades a ser actualizadas. Los nombres de propiedades son las mismas que las utilizadas en la representación GET.
PUT se comporta igual que el POST.
OPTIONS devuelve una lista de los métodos permitidos.
DELETE eliminará el recurso especificado. El cuerpo debe ser un 'json' válido y se deben especificar estas propiedades:
- usuario - el nombre de la aplicación que está solicitando la actualización; y
- api_key - una clave válida para verificar que está autorizado para modificar el recurso.
Contactos
Los contactos existen como recursos por derecho propio. Se puede acceder a ellos de forma estándar.
Enumerar todos los contactos: | https://collections.ala.org.au/ws/contacts |
Obtener detalles de un contacto específico | https://collections.ala.org.au/ws/contacts/31 |
Encontrar un contacto por su dirección de correo electrónico | https://collections.ala.org.au/ws/contacts/email/dave.martin@csiro.au |
La edición de contactos sigue el mismo patrón que las entidades principales . PUT y POST se actualizará un contacto si se especifica un 'id' en la 'url', además se añade un nuevo contacto. DELETE eliminará un contacto.
El cuerpo debe ser una llamada json válida y usted debe especificar al menos estas propiedades:
- usuario - el nombre de la aplicación que está solicitando la actualización; y
- api_key - una clave válida para verificar que está autorizado para modificar el recurso.
y también puede especificar
- Nombre
- Apellido
- fax
- teléfono
- teléfono móvil
- notas
- público (verdadero o falso) - controla si el contacto se mostrará en una página web pública
Tenga en cuenta que los contactos no tienen UIDs. En su lugar usan los IDs asignados en la BD sin procesar.
El correo electrónico del usuario es efectivamente la clave principal para un contacto. Compruebe siempre si existe un contacto (mediante la búsqueda de su dirección de correo electrónico) antes de crear uno.
Relaciones entre contactos
Un contacto puede estar asociado con varios recursos. Un recurso puede tener muchos contactos. La relación entre un contacto y un recurso tiene sus propios metadatos tales como el rol que tiene el contacto en relación con el recurso, los derechos de edición de contacto, etc.
Este metadato es accecido por anexación contactos el URI de un recurso utilizando el formulario: | |
GET https://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts | |
Por ejemplo: | https://collections.ala.org.au/ws/collection/co13/contacts |
Los metadatos tienen la forma para una relación específica de contacto: | |
GET https://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/{id} | |
Por ejemplo: | https://collections.ala.org.au/ws/collection/co13/contacts/20 |
Los contactos principales para todos los casos de un tipo de recurso a los que se puede acceder utilizando el formulario: | |
GET https://collections.ala.org.au/ws/{resource type}/contacts | |
Por ejemplo: | https://collections.ala.org.au/ws/collection/contacts |
Los contactos pueden elegir ser notificados cuando se produzcan eventos importantes en un recurso. La lista de contactos para ser notificados para un recurso específico puede recuperarse de un 'uri' de la forma: | |
GET https://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/notifiable | |
Por ejemplo: | https://collections.ala.org.au/ws/collection/co13/contacts/notifiable |
Puede recuperar todas las entidades que el contacto especificado está autorizado a editar. El uri tiene la forma: | |
GET https://collections.ala.org.au/ws/contacts/{contact id}/authorised | |
Por ejemplo: | https://collections.ala.org.au/ws/contacts/132/authorised |
Todos los servicios de contacto se pueden cargar como CSV, XML o JSON mediante negociación del contenido.
Más información.
Las relaciones del contacto pueden actualizarse siguiendo las normas habituales. El contacto ya debe existir.
POST añadirá el contacto a un recurso si no existe previamente o actualizará la relación utilizando los datos 'json' en el cuerpo de la solicitud.
El cuerpo debe ser un json válido y usted debe especificar al menos estas propiedades:
- usuario - el nombre de la aplicación que está solicitando la actualización; y
- api_key - una clave válida para verificar que está autorizado para modificar el recurso.
y también puede especificar
- rol - rol que tiene el contacto para este recurso, por ejemplo: 'Gestor'
- notificar (verdadero o falso) - si el contacto desea ser notificado sobre eventos importantes (esto ha sido reemplazado por Alertas)
- administrador - si al contacto se le permite administrar este recurso
- contactoPrincipal - si el contacto es el contacto principal para este recurso
El formulario de la url es https://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/{contact id}
PUT igual como POST.
DELETE eliminará el contacto de un recurso.
El cuerpo debe ser un json válido y usted debe especificar al menos estas propiedades:
- usuario - el nombre de la aplicación que está solicitando la actualización; y
- api_key - una clave válida para verificar que está autorizado para modificar el recurso.
La dirección url tiene la misma forma que el anterior.
Intercambio de metadatos EML
El registro ofrece un servicio para extraer metadatos del recurso en formato EML. La respuesta cumple con Esquema EML de GBIF. Este documento es adecuado para su inclusión en un Darwin Core Archive como la descripción de metadatos de los archivos contenidos. La forma es:
GET https://collections.ala.org.au/ws/eml/{uid} | |
Este ejemplo de uri devuelve un documento XML que describe el conjunto de registros de observaciones o especímenes del Portal de Datos DECCW de NSW Wildlife: | https://collections.ala.org.au/ws/eml/dr368 |
Servicios de citación
Los servicios de citas devuelven información sobre la atribución y la licencia para los registros digitalizados a los que se puede acceder a través del Portal de Datos.
Citas para una lista de publicadores de datos
Este servicio acepta una lista de UIDs de entidad y devuelve la información de la cita para cada entidad. Puede especificar cualquier tipo de entidad, pero sólo los juegos de datos tienen información significativa de la cita. Para cada entidad, el servicio devuelve el nombre de la entidad, su texto de la cita, el texto de sus derechos y una cadena de 'más información' que contiene un enlace a la página de la colección de la entidad. La forma es:
GET https://collections.ala.org.au/ws/citations/{listOfUIDs} | |
donde listaDeUIDs es una lista de UID separada por comas. | |
Este ejemplo de 'uri' devuelve una lista de citas para los tres juegos de datos especificados: | https://collections.ala.org.au/ws/citations/dr368,dr105,dr357 |
El servicio puede devolver la información como una lista JSON o un archivo CSV o TSV con los encabezamientos apropiados. El formato se especifica mediante content-negotiation http .
Más información.
Servicios de búsqueda
Estos servicios soportan explícitamente las interoperaciones con otros componentes del Portal de Datos como el bio-cache y el BIE. No todos cumplen con los principios RESTful, pero se están refactorizando progresivamente para hacerlo .
Mapea un registro del bio-cache para una colección
Este servicio toma un código de una colección y de una institución de un registro de especímenes sin procesar y mapea la combinación a una sola colección. El formulario es:
GET https://collections.ala.org.au/lookup/inst/{institution-code}/coll/{collection-code} | |
Este ejemplo uri devuelve los metadatos para la Colección de Insectos Nacional Australiana: | https://collections.ala.org.au/lookup/inst/ANIC/coll/Insects |
More information. |
Obtener un resumen para una entidad
Este servicio solo devuelve un subconjunto de metadatos de una entidad. La forma es:
GET https://collections.ala.org.au/lookup/summary/{uid} | |
Este ejemplo de uri devuelve los metadatos para el publicador de datos de Aves de Australia: | https://collections.ala.org.au/lookup/summary/dp28 |
Los servicios de resumen son menos útiles ahora que tenemos servicios de metadatos full RESTful pero se mantienen por compatibilidad con versiones anteriores. También ofrecen una eficacia pequeña cuando el servicio se llama repetidamente como durante las operaciones de indización. Más información.
Búsqueda el nombre de una entidad
Este servicio es aún más reducido que el resumen. Devuelve solo el nombre de una entidad dado su UID. La forma es:
GET https://collections.ala.org.au/lookup/name/{uid}
Obtener sugerencias para la cobertura taxonómica para una entidad
Este servicio influye en la vinculación del nombre taxonómico durante el procesamiento de registros en bruto del bio-cache. Cuando un registro ha sido asignado a una colección, los metadatos de la colección pueden utilizarse para informar sobre el proceso de vinculación de registros otorgando más peso a las coincidencias de determinados grupos taxonómicos. La forma es:
GET https://collections.ala.org.au/lookup/taxonomicCoverageHints/{uid} | |
Este ejemplo de uri devuelve una lista de pares rango-nombre que describen un rango taxonómico: | https://collections.ala.org.au/lookup/taxonomyCoverageHints/co12 |
Enumerar los límites de descarga para todos los juegos de datos
Pueden aplicarse límites al número de registros que puede descargarse desde un recurso particular por petición. If [ ] es devuelto, no existen límites establecidos actualmente. La forma es:
GET https://collections.ala.org.au/lookup/downloadLimits
Generar UID para una nueva entidad
Este es un servicio temporal utilizado cuando se descubren nuevos recursos de datos durante la recolección de registros. Este servicio desaparecerá cuando el proceso de recolección sea actualizado. Los servicios estándar de datos se utilizarán para crear el nuevo recurso y devolver el UID asignado por la colección. La forma es:
GET https://collections.ala.org.au/lookup/generateDataResourceUid
Servicios de sincronización de datos
Sincronizar datos desde GBIF instalaciones o instalaciones del IPT:
IPT
Actualice la lista de juegos de datos registrados en la colección de un IPT utilizando una URL como la de abajo.
GET https://collections.ala.org.au/ipt/scan?create=true&isShareableWithGBIF=false&uid={uid}&apiKey=XXXXXX |
GBIF
Actualice la lista de juegos de datos descargados desde GBIF utilizando una URL como la de abajo.
GET https://collections.ala.org.au/gbif/scan?uid={uid}&apiKey=XXXXXX |