Application Programming Interfaces (APIs)
This page presents an overview of all APIs that are served by the SoilWise Catalogue for (1) internal processing, (2) reuse of SoilWise data and functionality and (3) to enable future integration with other systems, particularly with EUSO. Information on interfaces is also available in a dedicated subchapter per each Technical Component.
Data Preview & Publication APIs
These APIs allow discovery of (meta)data and knowledge. Most of them are mostly meant to be used as part of SWC backend mechanisms to access or harvest remote data and knowledge resources or to process these resources internally. However, some of them are also relevant for end user discovery of content from SWC. Those user-facing discovery APIs are used in user interface components developed by SoilWise, but could also be employed for integration with the EU Soil Observatory and other existing systems that want to make use of SWC.
| Service | Documentation | Purpose |
|---|---|---|
| Catalogue Service for the Web (CSW) | Swagger UI | Catalogue service for the web (CSW) is a standardised pattern to interact with (spatial) catalogues, maintained by OGC. This API is provided by pycsw. |
| OGC API - Records | Swagger UI | OGC is currently in the process of adopting a revised edition of its catalogue standards. The new standard is called OGC API - Records. OGC API - Records is closely related to Spatio Temporal Asset Catalogue (STAC), a community standard in the Earth Observation community. This API is provided by pycsw. |
| Protocol for metadata harvesting (OAI-PMH) | Swagger UI | The open archives initiative has defined a common protocol for metadata harvesting (oai-pmh), which is adopted by many catalogue solutions, such as Zenodo, OpenAire, CKAN. The oai-pmh endpoint of Soilwise can be harvested by these repositories. This API is provided by pycsw. |
| Spatio Temporal Asset Catalog (STAC) | Swagger UI | A modern, JSON-based standard for describing and discovering geospatial assets. It is widely used in the Earth Observation community to expose datasets (e.g., satellite imagery, raster data) along with their spatial and temporal metadata. The STAC API enables clients to search, filter, and retrieve collections and items using a RESTful interface. This API is provided by pycsw. |
| OpenSearch | Swagger UI | OpenSearch provides a lightweight, URL-based search interface for querying metadata in the catalogue. It allows clients to perform simple searches using query parameters such as free text (q), spatial filters (bbox), and temporal constraints (time). Responses are typically returned in Atom or JSON formats, making it easy to integrate with web browsers, GIS tools, and other clients. OpenSearch serves as a simpler alternative to more complex catalogue interfaces like CSW. This API is provided by pycsw. |
| SPARQL | Swagger UI | The API allows query access to the SoilWise knowledge graph, thus offering querying on linked data, traversing relationships between entities that are relevant and cannot be represented in conventional relational databases. This API is provided by Soil-health Knowledge Graph and Virtuoso Triple Store. |
| Solr Search API | Swagger UI | Full-text and faceted search over harvested metadata records via the Solr index. The Search API serves the Search UI and can be used by external clients. Queries the records_active Solr collection. |
Processing APIs
SWC processing APIs are mostly interfaces to components that have been developed or adapted to support the processing of metadata (e.g. metadata augmentation, transforming to RDF) or to support quality assurance and visualisation.
| Service | Documentation | Purpose |
|---|---|---|
| Link Liveness Assessment API | Swagger UI | The linkchecker component is designed to evaluate the status, validity and accuracy of links within metadata records in an OGC API - Records based system. Its responses provide input that is used to inform end users about the status of published links and to collect required data for quality control. |
| Search-API (Solr Indexing) | Swagger UI | The Search API also handles indexing: it processes (augmented) metadata stored in the catalogue database into the Solr index (records_active / records_shadow collections). This is the same service as the Solr Search API above, with indexing as an internal processing function. |
| DOI resolution API | Swagger UI | Checks the status, metadata, and validity of a given Persistent Identifier (such as a DOI) across various platforms (Soilwise Catalogue, OpenAire, DataCite). Enables suggestion to add a specific DOI to the Soilwise Catalogue. Validates the DOI upstream before recording the suggestion in the database. More info can be found in Data publication support tools |
| Soil Mission news feed API | Swagger UI | Retrieves a paginated list of feed items, optionally filtered by keywords and associated projects. |
| History API | Swagger UI | Retrieves the harvesting and version history of a specific record by its identifier. |
| SoilVoc API | Browser | The SoilVoc vocabulary is accessible as a browsable HTML interface (GitHub Pages) and in machine-readable form via the SPARQL endpoint. The vocabulary terms are maintained in CSV format in GitHub and published as SKOS RDF. |
| CSVW API | Swagger UI | API for converting soil observation data into RDF and SQLite formats. |