Technical interoperability II: API

Interoperability in Climate and Atmospheric sciences
FAIR NetCDF Data

The Problem

How can one computer system access data held by another system?

Ash, a researcher

Notion of technical interoperability

What is technical interoperability?

Tecnical interoperability refers to the ability of software systems to reliably exchange data and metadata without human intervention

  • standardized protocols like OPeNDAP
  • APIs (Application Programming Interfaces) that define how software systems can interact with each other in a structured and predictable way

01 What are APIs

An API (Application Programming Interface) defines how one software system can interact with another in a structured and predictable way.

Customer, waiter, chef analogy

Client and server communicating through an API, and the waiter analogy: customer, waiter, chef

02 APIs can take different forms depending on where and how systems communicate

Library APIs

Library or programming APIs allow software code to interact with functions, classes, or modules provided by a software package.

OS APIs

Operating system APIs allow applications to interact with system resources such as files, memory, or hardware.

Database APIs

Database APIs allow applications to query and modify information stored in databases.

Web APIs

Web APIs provide a machine-accessible interface through which one system can request data or services from another over the web.

03 Web APIs usually define:

  1. Endpoints: the address of the resource exposed by the API
  2. HTTP methods: they use a shared vocabulary of methods. GET, POST, PUT, DELETE to define how to exchange resources across the web.
  3. Parameters: additional information to refine the request
  4. Representation: most Web APIs today use the JSON format to exchange data.
  5. Authentication: mechanism to identify users or software and determine which operations they are allowed to perform.

APIs connect structural and semantic interoperability

Structural interoperability

JSON responses must follow well defined schemas

→

APIs

←

Semantic interoperability

Metadata fields, controlled terms ensure that machines interpret content consistently

Without structural and semantic agreement, an API may be technically functional but scientifically meaningless.

04 Why APIs are relevant for research : A typical workflow

Query a data service from radar observations

→

Retrieve metadata and identify data files

→

Process the selected data in Python

→

Generate derived products

→

Publish the results and metadata to a research repository

True or False Exercise

A Web API can allow software to retrieve data from a repository without a user manually interacting with the repository website.

True

All APIs are Web APIs.

False

Web API must return JSON in order to be technically interoperable.

False

If two systems can exchange data through an API, this automatically means that they interpret the scientific meaning of the data in the same way.

False

APIs remove the need for structural and semantic interoperability.

False : Data still need predictable structures and shared meaning to be reused correctly!!

Hands on 4TU.ResearchData Web API

05 Hands-on: 4TU.ResearchData Web API

The Unix terminal allows HTTP requests using curl.

curl = client URL > send requests and receive responses.

curl -X <HTTP_METHOD> <URL> -H "<HEADER_KEY>: <HEADER_VALUE>" -d '<BODY_DATA>'

Exercise 1: checking the connection with the server using the web browser and curl in the Unix terminal

  • Open a web browser and write: https://data.4tu.nl/v2/articles

  • On the Unix terminal write:

    curl -X GET https://data.4tu.nl/v2/articles | jq

  • How are both responses compared to each other?

Exercise 2: Exploring the 4TU.ResearchData API documentation:

API documentation: https://data.4tu.nl/api/docs

  1. Show in the terminal the metadata of 2 datasets published since May 1st 2025 using curl and jq to format the output.
  2. Save the information of 2 datasets published since May 1st 2025 using curl to a file called data.json in the current directory.
  3. Show in the screen the metadata of 10 software published since January 1st 2025.

Key takeways

  • APIs operationalize technical interoperability by enabling standardized machine-to-machine interaction.

  • Web APIs use HTTP methods, predictable endpoints, JSON representations, stable identifiers, and authentication mechanisms.

  • APIs depend on structural interoperability (schemas) and semantic interoperability (controlled vocabularies).

  • Command-line tools such as curl provide direct access to API functionality and enable automation.

  • The 4TU.ResearchData API supports full dataset lifecycle management: discovery, creation, metadata update, file upload, and submission for review