OpenAIRE Graph API

Welcome to the OpenAIRE Graph API code repository!

This repository houses the latest implementation of the OpenAIRE Graph API, designed to facilitate seamless access to metadata records of research products (i.e., publications, data, software, other research products), and projects within the OpenAIRE Graph.

For more information, please take a look at our documentation page.

Getting Started

Prerequisites

• Java 21 (tested using OpenJDK 21.0.2)
• Maven 3.6+
• Docker (optional, for containerized deployment)

Configuration

The application uses application.properties for configuration. Key properties include:

Solr Configuration

The application supports two connection modes for Solr:

• solr.direct-connection.enabled - Set to true for direct HTTP connection, false for ZooKeeper connection

Direct Connection Mode (when solr.direct-connection.enabled=true):

• solr.url - Solr server URL (e.g., http://solr1-v9-coordinator.openaire.eu:8983/solr/public)

ZooKeeper Connection Mode (when solr.direct-connection.enabled=false):

• solr.zkHosts[0], solr.zkHosts[1], solr.zkHosts[2] - ZooKeeper host addresses
• solr.collection - Solr collection name (e.g., public)

Running Locally

Option 1: Using Maven (Recommended for development)

mvn spring-boot:run

Option 2: Using IntelliJ IDEA

1. Open the project in IntelliJ
2. Find src/main/java/eu/openaire/api/OpenaireRestApiApplication.java
3. Right-click and select "Run 'OpenaireRestApiApplication'"

The application will be accessible at: http://localhost:8080/graph

Swagger UI: http://localhost:8080/graph/swagger-ui/index.html

Docker Support

Build the Docker image

# Build the project and create Docker image
mvn clean package
docker build -t graph-api-[beta|prod]-x.y.z:latest .

Run with Docker Compose

# Start the container
docker-compose up -d

# Stop the container
docker-compose down

Environment Variables

When running in Docker, you can override configuration using environment variables:

Solr Configuration:

• SOLR_DIRECT_CONNECTION_ENABLED - Overrides solr.direct-connection.enabled (true/false)
• SOLR_URL - Overrides solr.url (used in direct connection mode)
• SOLR_ZKHOSTS_0 - Overrides solr.zkHosts[0] (used in ZooKeeper mode)
• SOLR_ZKHOSTS_1 - Overrides solr.zkHosts[1] (used in ZooKeeper mode)
• SOLR_ZKHOSTS_2 - Overrides solr.zkHosts[2] (used in ZooKeeper mode)
• SOLR_COLLECTION - Overrides solr.collection (used in ZooKeeper mode)

Other Configuration:

• SCHOLIX_SERVER_BASE_URL - Overrides scholix.server-base-url
• OPENAPI_SERVER_BASE_URL - Overrides openapi.server-base-url
• SERVER_SERVLET_CONTEXT_PATH - Overrides server.servlet.context-path

These are configured in docker-compose.yml (local) and docker-compose-beta.yml (beta environment).

Git Flow

• master — production-ready code, deployed to production
• develop — integration branch, deployed to beta
• Feature branches — created from develop for new work

Workflow

1. Create a feature branch from develop (e.g., task-id-my-feature)
2. Develop and test on the feature branch
3. Merge the feature branch into develop via pull request
4. Deploy develop to beta for testing
5. When ready for production, merge develop → master
6. On master: remove -SNAPSHOT from pom.xml version (e.g., 1.3.0-SNAPSHOT → 1.3.0)
7. Tag master with the version (e.g., git tag v1.3.0 && git push origin --tags)
8. Checkout the tag (e.g., git checkout v1.3.0)
9. Build & deploy from the tag
10. On develop: change version to next SNAPSHOT (e.g., 1.4.0-SNAPSHOT)
11. If issues arise → redeploy from the previous tag (git tag --list to see available versions)

Building and Pushing Docker Images to OpenAIRE Registry

Login to the OpenAIRE Docker registry:

docker login https://docker-registry.openaire.eu

For beta environment:

docker build --platform linux/amd64 -t graph-api-beta-x.y.z:latest .
docker tag graph-api-beta-x.y.z:latest docker-registry.openaire.eu/graph-api/graph-api-beta-x.y.z:latest
docker push docker-registry.openaire.eu/graph-api/graph-api-beta-x.y.z:latest

For production environment:

docker build --platform linux/amd64 -t graph-api-prod-x.y.z:latest .
docker tag graph-api-prod-x.y.z:latest docker-registry.openaire.eu/graph-api/graph-api-prod-x.y.z:latest
docker push docker-registry.openaire.eu/graph-api/graph-api-prod-x.y.z:latest