Improve federation support

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New property `id` added to `FederationBackend` objects returned by `listFederation` in `Capabilities`
+- New functions `getFederationBackend` and `getFederationBackends` in `Capabilities`
+
 ## [2.7.0] - 2025-01-04
 
 ### Added

openeo.d.ts

@@ -409,6 +409,20 @@ declare module OpenEO {
          * @returns {Array.<FederationBackend>} Array of backends
          */
         listFederation(): Array<FederationBackend>;
+        /**
+         * Given just the string ID of a backend within the federation, returns that backend's full details as a FederationBackend object
+         * 
+         * @param {string} backendId - The ID of a backend within the federation
+         * @returns {FederationBackend} The full details of the backend, or `null` if no backend with the given ID exists
+         */
+        getFederationBackend(backendId: string): FederationBackend | null;
+        /**
+         * Given a list of string IDs of backends within the federation, returns those backends' full details as FederationBackend objects
+         * 
+         * @param {Array<string>} backendIds - The IDs of backends within the federation
+         * @returns {Array<FederationBackend>} An array in the same order as the input, containing for each position either the full details of the backend, or `null` if no backend with the given ID exists
+         */
+        getFederationBackends(backendIds: Array<string>): Array<FederationBackend | null>;
         /**
          * Lists all supported features.
          *
@@ -2958,7 +2972,7 @@ declare module OpenEO {
      */
     export type Process = object<string, any>;
     /**
-     * An array of backends in the federation.
+     * A back-end in the federation.
      */
     export type FederationBackend = {
         /**
@@ -2997,7 +3011,7 @@ declare module OpenEO {
     /**
      * An array, but enriched with additional details from an openEO API response.
      *
-     * Adds three properties: `url`, `links` and `federation:missing`.
+     * Adds two properties: `links` and `federation:missing`.
      */
     export type ResponseArray = any;
     export type ServiceType = object<string, any>;

src/capabilities.js

@@ -198,7 +198,37 @@
 	 * @returns {Array.<FederationBackend>} Array of backends
 	 */
 	listFederation() {
-		return Array.isArray(this.data.federation) ? this.data.federation : [];
+		let federation = [];
+		if (Utils.isObject(this.data.federation)) {
+			// convert to array and add keys as `id` property
+			for(const [key, backend] of Object.entries(this.data.federation)) {
+				// fresh object to avoid `id` showing up in this.data.federation
+				federation.push({ id: key, ...backend });
+			}
+		}
+		return federation;
+	}
+
+	/**
+	 * Given just the string ID of a backend within the federation, returns that backend's full details as a FederationBackend object
+	 * 
+	 * @param {string} backendId - The ID of a backend within the federation
+	 * @returns {FederationBackend | null} The full details of the backend, or `null` if no backend with the given ID exists
+	 */
+	getFederationBackend(backendId) {
+		// Add `id` property to make it a proper FederationBackend object, but check for null case beforehand
+		return this.data.federation[backendId] ? { id: backendId, ...this.data.federation[backendId] } : null;
+	}
+
+	/**
+	 * Given a list of string IDs of backends within the federation, returns those backends' full details as FederationBackend objects
+	 * 
+	 * @param {Array<string>} backendIds - The IDs of backends within the federation
+	 * @returns {Array<FederationBackend | null>} An array in the same order as the input, containing for each position either the full details of the backend, or `null` if no backend with the given ID exists
+	 */
+	getFederationBackends(backendIds) {
+		// Let 'single case' function do the work, but pass `this` so that `this.data.federation` can be accessed in the callback context
+		return backendIds.map(this.getFederationBackend, this);
 	}
 
 	/**

src/pages.js

@@ -21,7 +21,7 @@ class Pages {
    * @param {Connection} connection
    * @param {string} endpoint
    * @param {string} key
-   * @param {Constructor} cls
+   * @param {Constructor} cls - Class
    * @param {object} [params={}]
    * @param {string} primaryKey
    */

src/typedefs.js

@@ -196,14 +196,15 @@
  */
 
 /**
- * An array of backends in the federation.
+ * A back-end in the federation.
  * 
  * @typedef FederationBackend
  * @type {object}
+ * @property {string} id ID of the back-end within the federation.
  * @property {string} url URL to the versioned API endpoint of the back-end.
  * @property {string} title Name of the back-end.
  * @property {string} description A description of the back-end and its specifics.
- * @property {string} status Current status of the back-ends (online or offline).
+ * @property {string} status Current status of the back-end (online or offline).
  * @property {string} last_status_check The time at which the status of the back-end was checked last, formatted as a RFC 3339 date-time.
  * @property {string} last_successful_check If the `status` is `offline`: The time at which the back-end was checked and available the last time. Otherwise, this is equal to the property `last_status_check`. Formatted as a RFC 3339 date-time.
  * @property {boolean} experimental Declares the back-end to be experimental.
@@ -213,7 +214,7 @@
 /**
  * An array, but enriched with additional details from an openEO API response.
  * 
- * Adds three properties: `links` and `federation:missing`.
+ * Adds two properties: `links` and `federation:missing`.
  * 
  * @typedef ResponseArray
  * @augments Array