Federated Learning API

With SymetryML Federated Learning can be organized in a centralized manner, where only the administrator has access to information sharing and model building, or a decentralized framework where all peers in the federation have access to information sharing and model building. There is also the option to create a hybrid Federated Learning network which can be a combination of centralized and decentralized federated learning networks.

Creating a federation starts with a single node, the Administrator of the Federation. The administrator is responsible for creating the federation, inviting peers to join the federation, and determining how often the federation will share information, otherwise known as the “sync” schedule or frequency of sharing information.

For more details on the various topologies available when using federated learning with SymetryML please consult Federated Learning Topologies documentation.

Version 6.3 Endpoint Updates: Several REST endpoints have been renamed for clarity in version 6.3 (e.g., getEncrypted → getInvitation). Legacy endpoint names remain available for backward compatibility.

Federated Learning: Create Federation

Please consult the following for details on how to create a federation depending on if you are using [NATS] (https://www.nats.io) or AWS backed federation.

• AWS : Consult this section
• NATS : Consult this section

Federated Learning: Get Federation Info

This rest call returns the information about the federation. The information is returned encrypted with the user secret key, that is the SymetryML user key.

URL

GET /symetry/rest/{cid}/fedml/{pid}/info

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request:
GET url="http://charm:8080/symetry/rest/c1/fedml/nh_test_admin/info"

Response:
{"statusCode":"OK","statusString":"OK","values":{"fedInfoEncrypted":"mD3yV8TamG8BsXx/kGGqtnXm+O6njUfyKnH5U86fldQ7Lbsp0t6V5rAM7zhqtMaQsHPodR/5ATf5ovKTlnUSNkWQKkrbaQDR+rHnOymTcyfahXihXoccar67oE+VVYGJDQpDB7IOEVnKKzdFWqBxlHzLzGip0vFGcnfTXR3689oVB5BDbOSvsGkxfjRMoZBJLLVskN4yqmq+kbP5lrP+zuhR5NpTKCrPIe9phIiWlURzHb2RxsI6LHGhySz9iKytesYD4Kdl8iOzfffdx/jPDewreaks2Cx5RFobHPxfuBHYWHzLn2DISlxO+Pemg3Rq0FCZ7Hk9Fexps04yTxkk7S9iBDEWDufCK4cRIEYq1/feytV/Olv2a+OZDlpG38aHyk6uiYzpx22R8DJLoTjBW8Cp/JFgokyYdx29bM2MqlsfUSxIEulbfjoymdtu95PT4YjUelogTctAn9+/xnWiyrET3Fp9VqkCFnXuIdCm5udWspqr7sconMe1rgss5AMPbwqEAcabJR8rGl6zNQX6HgUOaIbKF7PpETMJvlLOby12uY0iljykqaZQNOTd1rjVmDXxxDlC7GcLinPpJE+WOGevGfrvcM71uIbDB1+a7Rz5QKvtW5X9RgL1rZtodXqiwpT1Br+THaKcrBnD45fG7EHBOwPNR4ue+uuvMi+57xLi1ntUIbPBJ7pzRZ09tkUCfh+aQvAbSoThna5Ef6XmTQ\u003d\u003d"}}

Federated Learning: Get Federation Invitation

This Rest endpoint is used in order to get 'an invite' to join the federation by the administrator of the federation. The body of the request contains the password to use to encrypt the resulting encryptedGroupInfo can then be shared with another peer so that they can join. Please note that encryptedGroupInfo can only be used 1 time. For each peer that want to join the federation a unique encryptedGroupInfo needs to be generated.

URL

POST /symetry/rest/{cid}/fedml/{pid}/getInvitation

Note: The legacy endpoint POST /symetry/rest/{cid}/fedml/{pid}/getEncrypted is also available for backward compatibility.

HTTP Response Entity Key.

HTTP Responses

HTTP Response Entity

The response will be stored in the encryptedGroupInfo entity which is a string. That string is a json encoded string encrypted with the provided password. Once decrypted you get a <string, string> map that contains some of the following key: The response token fed_req_token can only be used one time.

• sync_sched
• fed_name
• fed_secret_key
• fed_req_token
• for AWS based federation:
  • aws_topic_arn
  • aws_topic_region
• for NATS based federation:
  • nats_hosts
  • nats_sec_user
  • nats_sec_passwd
  • nats_sec_token
  • nats_sec_nkey_seed

Sample Request/Response

Request:
POST url="http://charm:8080/symetry/rest/c1/fedml/nh_test_admin/getEncrypted"

Request Body Before Encryption:
{"passwd":"passwd","fed_rest_host":"http://charm:8080"}

Request Body:
qvh4P1y937flTE/R6GgtrN8Weu28/jCx14zBIG5zk4CEqC4+rLL/HtVvKqUthPsSVZN8BgWP39O+MKEyOsUo8w==

Response:
{"statusCode":"OK","statusString":"OK","values":{"fedInfoEncrypted":"ZwsCbdhP2GxfOgDBwJHoy61uRMZLNg7D581Cs9zWAgjwWpK2wScvgpTexpsVyilbvGThFVsWXz57n9BXY+DA1EmI+L29H+K60b1lI4v/WLr45HHCdMEDCcBAL+F3/3NcRBl5RcfgBlC4RTV6+h/75rr21lgMGxnVXlYBoUh//JpBxfJhEZyxa1gv0WVdCXDDT/M3Aq819r+6rS89jj38SYj/Hzj7pJaEHvbxe+OniH5Z90xEortLZeVdG8HE5zzqLegKpChFYFE4l60RXtdyE/fa7uY3gM7Q/yU+8SQ3Yjkvl8B5Gs7coBdgkcKNmcgiBqG4YrQSg8SCuX6RsKs4B4qV61w+AZkmt9+ipp049Hpxwu0myZ2agomcAMKdZHDv"}}

Decrypted Message Example:

Once decrypted the Federation info will contain information like in the following example. This is basically a map with a few key/ value pair. These key value pairs must be used when joining a federation.

Decrypted JSON:
{
    "sync_sched":"m1",
    "fed_rest_url":"http://charm:8080/symetry/rest/c1/fedml/nh_test_admin/createPolicies",
    "fed_name":"nh_test_doc",
    "fed_secret_key":"t6Zat/ZAJyYBtmVXATUDCQ\u003d\u003d",
    "aws_topic_arn":"arn:aws:sns:us-east-1:428117700962:nh_test_doc",
    "aws_topic_region":"US_EAST_1",
    "fed_req_token":"FEDTOKEN38f45fe16545e80c",
}

Federated Learning: Join a Federation

Please consult the following sections for details on how to join an existing federation depending on if you are using NATS (www.nats.io) or AWS backed federation.

• AWS : Consult this section
• NATS : Consult this section

Federated Learning: Start Pulse

Instruct the federated project to start syncing with other nodes in the federation.

URL

GET /symetry/rest/{cid}/fedml/{pid}/startPulse

HTTP Responses

Federated Learning: Change Schedule

This rest endpoint can only be executed by the Federation Administrator. It enables a change of the synchronization schedule - that is, how often peers in the federation synchronize with other peers.

The ProjectInfo returned by the Project Info rest call contains information about whether or not a project is the federation administrator. This information is present in the param map field under the fed_is_admin key.

URL

GET /symetry/rest/{cid}/fedml/{pid}/newSchedule

Create Project Query Parameters

HTTP Responses

Federated Learning: Stop Pulse

Instruct the federation project to stop syncing with other nodes in the federation.

URL

GET /symetry/rest/{cid}/fedml/{pid}/stopPulse

HTTP Responses

Federated Learning: Manual Sync

Send a single synchronization request message to the federation. This is used when a given peer/client wants to receive synchronization info from the other peers in the federation.

URL

GET /symetry/rest/{cid}/fedml/{pid}/fullSyncRequest

HTTP Responses

Allows Peer Explore for a Given Node

Send a single synchronization request message to the federation. This is used when a given peer/client wants to receive synchronization info from the other peers in the federation.

URL

GET /symetry/rest/{cid}/fedml/{pid}/setExplorePeers

Query Parameters

HTTP Responses

Validate Contract

Validates contract rules against the project schema before applying them. See the Federation Contract section for additional information. The body of the request is a StringList which contains a list of business rules to be enforced.

URL

POST /symetry/rest/{cid}/fedml/{pid}/contractValidate [body=StringList]

HTTP Responses

Add Contract

Adds a contract to a federated project to define data sharing rules. Only the federation admin can invoke this REST endpoint. See the Federation Contract section for additional information. The body of the request is a StringList which contains a list of business rules to be enforced. Please note that the contract is not validated automatically, so care must be taken to invoke Validate Contract first.

URL

POST /symetry/rest/{cid}/fedml/{pid}/addContract [body=StringList]

HTTP Responses

HTTP Response Entity

The response is a String entity. If the contract is not valid, it will contain a description of the error in the contract.

Federated Learning: Get Error Log

Return error logging messages. For federated project many things can happen in the background some of which that may cause errors, invalid AWS credentials, invalid S3 bucket path for example. This rest endpoint enables the checking for various error that might occur asynchronously in the background.

URL

GET /symetry/rest/{cid}/fedml/{pid}/getErrorLog

HTTP Responses

HTTP Response Entity

Clear Federation Error Log

Clear the federation error log for this node.

URL

DELETE /symetry/rest/{cid}/fedml/{pid}/clearErrorLog

HTTP Responses

Get Sync Log

Return synchronization logging messages.

URL

GET /symetry/rest/{cid}/fedml/{pid}/getSyncLog

HTTP Responses

HTTP Response Entity

Sample Request/Response Fed Create - Bad S3 bucket

GET url="http://charm:8080/symetry/rest/c1/fedml/kkg-node1/getErrorLog"

Response:
{"statusCode":"OK","statusString":"OK","values":{"stringList":["com.amazonaws.services.s3.model.AmazonS3Exception: Access Denied (Service: Amazon S3; Status Code: 403; Error Code: AccessDenied; Request ID: BECB121F96D0DA27; S3 Extended Request ID: iSi3fe/l6B8pTtVx4dovZ4OM/5PwDRRbEmpzoZaylnL3SuFibSrnMY1LkwMFpjUaO6LouBJEu1g\u003d), S3 Extended Request ID: iSi3fe/l6B8pTtVx4dovZ4OM/5PwDRRbEmpzoZaylnL3SuFibSrnMY1LkwMFpjUaO6LouBJEu1g\u003d"]}}

Get Federation Sync Statistics

Return information about status of the various synchronization. This is specially useful when using Federation Contracts and you want to know if other peers in the federation have contract validation failures and how many. Please see the FedSyncStats data structure for details.

URL

GET /symetry/rest/{cid}/fedml/{pid}/syncStats

HTTP Responses

HTTP Response Entity

Sample Request/Response Sync Stats

Request:
GET url="http://charm:8080/symetry/rest/c1/fedml/fedProject1/syncStats"

Response:
{
    "statusCode":"OK",
    "statusString":"OK",
    "values":{
        "fedSyncStats":{
            "sndCount":15,
            "sndContractError":2,
            "rcvCount":42,
            "rcvError":3,
            "rcvContractError":{
                "peer-node-1":1,
                "peer-node-3":1
            },
            "errorLog":["Contract validation failed: COUNT(fraud_cases) < 500"],
            "syncLog":["Sync completed successfully at 2025-01-15T10:30:00Z","Sync completed successfully at 2025-01-15T11:30:00Z"]
        }
    }
}

Get AWS Info

This rest endpoint is provided so that one can inspect the AWS resources utilized by the federation.

URL

POST /symetry/rest/{cid}/fedml/{pid}/awsinfo [body=Encrypted Map]

Request Body Map Keys

HTTP Responses

HTTP Response Entity

Sample Request/Response

Request
POST url="http://charm:8080/symetry/rest/c1/fedml/awsinfo"

Response Header:
Location: http://charm:8080/symetry/rest/c1/jobs/4

Response:
{"statusCode":"ACCEPTED","statusString":"Job Created","values":{}}

Job Request:
GET url="http://charm:8080/symetry/rest/c1/jobs/4