EVERSE services interconnection

[vuillaut]

We are now in the phase of interconnecting the different services that we have been building until now, which is very exciting as it will enhance their individual value.
I open this discussion to discuss possible solutions and issues.

[vuillaut]

Proposal with API endpoints

In order to tackle this problem in a shared and common way, I'd like to propose a solution I have implemented in the indicators repository.

Each repo can build an "API endpoint" in the form of a JSON file in its CI.
These JSON files aggregate the data from one repo into a singular JSON file push in the GitHub pages that can be easily fetch by other services.

Indicators and dimensions example

Here is the example for the indicators and dimensions:
https://github.com/EVERSE-ResearchSoftware/indicators?tab=readme-ov-file#api-endpoints

This is used by the TechRadar to validate the tools indicators and dimension when added to the repo by fetching the corresponding JSON files from the indicators pages:
EVERSE-ResearchSoftware/TechRadar#137

RSQKit example (example proposal)

As we now try to connect RSQKit with the other services, we could do the same for each repository to ease these connections.
The RSQKit could build a tasks.json file that would list all tasks, their URL, related quality indicators and tools:

RSQKit tasks.json example

{
  "metadata": {
    "version": "1.0.0",
    "lastUpdated": "2025-11-26T10:00:00Z",
    "totalTasks": 15,
    "baseUrl": "https://everse.software/RSQKit"
  },
  "tasks": [
    {
      "id": "licensing_software",
      "title": "Licensing software",
      "description": "How to apply a license to research software",
      "url": "https://everse.software/RSQKit/licensing_software",
      "relativePath": "pages/your_tasks/licensing_software.md",
      "contributors": [
        "Daniel Garijo",
        "Aleksandra Nenadic",
        "Shoaib Sufi",
        "Thomas Vuillaume"
      ],
      "qualityIndicators": [],
      "qualityDimensions": [
        {
          "identifier": "reusability",
          "name": "Reusability",
          "uri": "https://w3id.org/everse/dimensions/reusability"
        }
      ],
      "relatedTasks": [],
      "tools": [
        {
          "id": "spdx",
          "name": "SPDX License List",
          "url": "https://spdx.org/licenses/",
          "description": "The SPDX License List is an integral part of the SPDX Specification"
        },
        {
          "id": "choosealicense",
          "name": "Choose an open source license",
          "url": "https://choosealicense.com/",
          "description": "A tool to help you choose an open source license for your software"
        }
      ],
      "keywords": [
        "license",
        "copyright",
        "FAIR",
        "reusability",
        "intellectual property"
      ],
      "searchExclude": false,
      "lastModified": "2025-11-20"
    },
    {
      "id": "version_control",
      "title": "Version control",
      "description": "Version control systems in research software engineering",
      "url": "https://everse.software/RSQKit/version_control",
      "relativePath": "pages/your_tasks/version_control.md",
      "contributors": ["Giacomo Peru"],
      "qualityIndicators": [],
      "qualityDimensions": [
        {
          "identifier": "maintainability",
          "name": "Maintainability",
          "uri": "https://w3id.org/everse/dimensions/maintainability"
        }
      ],
      "relatedTasks": [],
      "tools": [
        {
          "id": "git",
          "name": "Git",
          "url": "https://git-scm.com/",
          "description": "Distributed version control system"
        },
        {
          "id": "github",
          "name": "GitHub",
          "url": "https://github.com/",
          "description": "Software development, sharing and version control platform"
        },
        {
          "id": "gitlab",
          "name": "GitLab",
          "url": "https://gitlab.com/",
          "description": "DevOps platform with version control"
        }
      ],
      "trainingResources": [],
      "keywords": [
        "version control",
        "git",
        "collaboration",
        "reproducibility"
      ],
      "searchExclude": false
    }
  ]
}

Advantages

• Each service can still be developed independently and expose its data to other services without sending them data
• no backend database, still run on GitHub pages

Drawbacks

• JSON schemas should be formalised to limit issues
• assumes that each repo maintains JSON generation correctly
• former versions of JSON files are not kept, each push to master generates a new version
• a shared github action template would help
• GitHub caching issues?

Please comment, upvote, downvote :)

[kennethrioja]

This is a neat solution, I've never thought about having an API in a GitHub page!

Indeed, this would be a convenient solution where we need to get the list of all pages from the RSQKit instead of cloning the whole repo (as discussed in EVERSE-ResearchSoftware/TechRadar#220 (comment)).

My questions:

1. Basically, TechRadar and RSQKit would need to have this implemented, right? What other services are on your mind?

2. You're saying that one drawback is:

assumes that each repo maintains JSON generation correctly

Would there be a 'standard' about the generated JSONs? Would there be strictly necessary data to generate? If so, we should provide guidelines on what are the strictly minimum data to generate. (Was it your point about JSON Schemas should be formalized to limit issues?)

3. For metadata, shouldn't we use https://schema.org/ as much as possible?

4. +1 on the shared GH action, to be able to trigger generate_api.py at the root of the repo or in scripts/?

5. Concerning the caching issues, I don't feel like a json API of a repo will be hit that much, what issues were you foreseeing?

[vuillaut]

My questions:

1. Basically, TechRadar and RSQKit would need to have this implemented, right? What other services are on your mind?

• Indicators and Dimensions are already implemented (but could be better documented, see point 2) ✅
• Links to training material might be needed, but they might have their own API already (?)
• resqui might expose its list of plugins (TBD)

2. You're saying that one drawback is:

assumes that each repo maintains JSON generation correctly

Would there be a 'standard' about the generated JSONs? Would there be strictly necessary data to generate? If so, we should provide guidelines on what are the strictly minimum data to generate. (Was it your point about JSON Schemas should be formalized to limit issues?)

Yes, that was my point.
We need to clearly define the schemas, document and version them.
When I implemented that solution for the indicators, I made something simple, but we would need to be more rigorous if we want to scale it to all repos.

3. For metadata, shouldn't we use https://schema.org/ as much as possible?

Yes, see point 2.

4. +1 on the shared GH action, to be able to trigger generate_api.py at the root of the repo or in scripts/?

• generate and fetch data
• trigger actions in other repos using repository_dispatch

5. Concerning the caching issues, I don't feel like a json API of a repo will be hit that much, what issues were you foreseeing?

GitHub pages and artifacts (here json file) are cached on client side. But the solution is actually simpler than I thought, the client simply needs to add a random version when fetching https://everse.github.io/repo/path/to/test.json?t=${timestamp}

[kennethrioja]

everse-training.app.cern.ch already has an API (as provided by the TeSS platform) https://everse-training.app.cern.ch/api/json_api

[shraddha-bajare]

Thank you, @vuillaut, for putting this proposal together.

Apologies for long message 😬

I am in agreement with the suggested approach. Exposing tasks.json from RSQKit is certainly beneficial. In this context, I feel that it should strictly include indicators along with dimensions, and we can track changes via API versioning to ensure consistency over time.

We could also develop a script to cross-verify TechRadar tools, dimensions, indicators against tasks.json. This script could list any discrepancies, and a separate workflow could automatically create GitHub issues highlighting these differences. This approach would help us synchronize tool reviews across both services more effectively.

Regarding the ongoing RSQKit × TechRadar work, a few additional points:

• Some work has already started by @npechl and myself, as reflected in issues #216
  and #217, While progressing on these, I considered whether we should link RSQKit tasks per segment page, per tool page, or both on TechRadar.
• My concern is that linking tasks in multiple places could lead to duplication or unnecessary complexity ??

If we decide to link tasks on both segment and tool pages, we need to carefully determine which tasks from tasks.json should be associated with individual TechRadar tool pages and which with TechRadar segment pages.

One potential solution could be:
Add all tasks (main + related tasks) to the TechRadar segment page only, and not to the individual tool pages.
Reason for this: Segment pages already list all tools per dimension, so all tasks would be directly visible and well organized.

where as, Include all quality indicators and helpsMeasure/helpsAchieve properties on the TechRadar tool pages.

Let me know if this feels good, Thanks