Skip to content

API documentation

Jump to bottom
Rafa Alvarez edited this page Aug 8, 2023 · 8 revisions

The API is split in differents levels or scopes: Cluster, node group, node and auth. This is the root of the URL to call the API

http://[GONARCH_SERVER]:2423/api/v1/[endpoint]

Cluster

Add

Description: Create a new cluster in your workspace.

Endpoint: cluster/add

Method: PUT

Parameters:

  • name: Cluster name. This field must be unique

  • primary: The Primary **IP **(not DNS) with port separated by :

  • repl_credentials: user and password for replicaion user in MySQL separated by :

  • promotion rule: The desired rules to decide if a node is promotable or not.:

    • Synced: Only replicas that are fully in sync with primary are candidates to an eventual promotion

    • Available: Any replica alive is a candidate to get promoted.

{
  "name": "mysql8-eu",
  "primary": "20.199.109.77:3306",
  "repl_credentials": "repl:repl",
  "promotion_rule" : "synced"
}

Output:

  • 0:.- OK: Cluster created

  • 1.- ERROR: The cluster name already exists

  • 2.- ERROR: Node not reachable. Either the IP + port or the user + pass are not correct

  • 3.- ERROR: Node not reachable. Either the IP + port or the user + pass are not correct

  • 4.- ERROR: The node used is not the primary.

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu", "primary": "20.199.109.77:3306", "repl_credentials": "repl:repl", "promotion_rule" : "synced"}' "http://127.0.0.1:2423/api/v1/cluster/add"

Remove

Description: Remove an existing cluster from your workspace.

Endpoint: cluster/remove

Method: DELETE

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB
{
  "name": "mysql8-eu"
}

Output:

  • 0:.- OK: Cluster removed

  • 1.- ERROR: The indicated cluster does not exists. Error in cluster name

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu"}' "http://127.0.0.1:2423/api/v1/cluster/remove"

Primary

Description: Retrieve the primary IP and port for a given cluster.

Endpoint: cluster/primary

Method: GET

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB
{
  "name": "mysql8-eu"
}

Output:

  • 1:.- ERROR: Cluster does not exists

  • GET Output

{
  "ip": "20.199.119.77",
  "port": 3306
}

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu"}' "http://127.0.0.1:2423/api/v1/cluster/primary"

List

Description: Summary of clusters created in that workspace.

Endpoint: cluster/list

Method: GET

Parameters:

  • none

Output:

  • 1.- WARNING: The cluster list is empty

  • GET output. What means each field?

[
  {
    "name": "mysql8-eu",
    "created_at": "2023-05-18 14:54:53",
    "huser": "repl",
    "hpass": "repl",
    "maint_mode": 0,
    "promotion_rule": "synced"
  }
]

Example:

$> curl -X PUT -H "Content-Type: application/json" "http://127.0.0.1:2423/api/v1/cluster/list"

Details

Description: Fetch all teh details for a given cluster.

Endpoint: cluster/details

Method: GET

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB
{
  "name": "mysql8-eu"
}

Output:

  • 1.- WARNING: The cluster list is empty

  • GET output. What means each field?

{
  "cluster_name": "mysql8-eu",
  "creation_date": "2023-05-18 14:54:53",
  "promotion_rule": "synced",
  "maintenance_mode": 0,
  "writer_endpoint": "192.168.1.154:3001",
  "reader_endpoint": "192.168.1.154:3002",
  "instances": [
    {
      "instance_id": 1,
      "instance_name": "mysql-europe-03",
      "hostname:port": "20.199.119.77:3306",
      "node_group": "mysql8-eu-ng-01",
      "reachable": 1,
      "access_level": "rw",
      "version": "8.0.33-0ubuntu0.20.04.2",
      "replication": {
        "replication_mode": "gtid",
        "role": "primary",
        "promotable": 0,
        "gtid_details": [
          {
            "source_instance": "mysql-europe-01",
            "coordinates": "1-53"
          },
          {
            "source_instance": "mysql-europe-03",
            "coordinates": "1-28"
          },
          {
            "source_instance": "mysql-europe-02",
            "coordinates": "1-17"
          }
        ]
      }
    },
    {
      "instance_id": 3,
      "instance_name": "mysql-europe-01",
      "hostname:port": "51.103.29.180:3306",
      "node_group": "mysql8-eu-ng-01",
      "reachable": 1,
      "access_level": "r",
      "version": "8.0.33-0ubuntu0.20.04.2",
      "replication": {
        "replication_mode": "gtid",
        "role": "replica",
        "promotable": 1,
        "replication_lag": 0,
        "io_thread_running": "Yes",
        "sql_thread_running": "Yes",
        "binlog_coordinates": "bin03.000005:132485",
        "gtid_details": [
          {
            "source_instance": "mysql-europe-01",
            "coordinates": "1-53"
          },
          {
            "source_instance": "mysql-europe-03",
            "coordinates": "1-471"
          },
          {
            "source_instance": "mysql-europe-02",
            "coordinates": "1-17"
          }
        ]
      }
    },
    {
      "instance_id": 2,
      "instance_name": "mysql-europe-02",
      "hostname:port": "20.188.59.210:3306",
      "node_group": "mysql8-eu-ng-01",
      "reachable": 1,
      "access_level": "r",
      "version": "8.0.33-0ubuntu0.20.04.2",
      "replication": {
        "replication_mode": "gtid",
        "role": "replica",
        "promotable": 1,
        "replication_lag": 0,
        "io_thread_running": "Yes",
        "sql_thread_running": "Yes",
        "binlog_coordinates": "bin03.000005:132485",
        "gtid_details": [
          {
            "source_instance": "mysql-europe-01",
            "coordinates": "1-53"
          },
          {
            "source_instance": "mysql-europe-03",
            "coordinates": "1-471"
          },
          {
            "source_instance": "mysql-europe-02",
            "coordinates": "1-17"
          }
        ]
      }
    }
  ]
}

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu"}' "http://127.0.0.1:2423/api/v1/cluster/details"

Edit promotion rule

Description: Edit the promotion rule for a given cluster.

Endpoint: cluster/edit/promotion_rule

Method: PUT

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB

  • flag: Option to change the cluster. Options:

    • Synced: Only replicas that are fully in sync with primary are candidates to an eventual promotion

    • Available: Any replica alive is a candidate to get promoted.

{
  "name": "europe-80-01",
  "flag": "available"
}

Output:

  • 0:.- OK: promotion rule changed and effective

  • 1.- ERROR: The indicated cluster does not exists. Error in cluster name

  • 2.- ERROR: Flag is not valid. Please select between synced or available. Use only one of those two flags

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu", "flag": "available"}' "http://127.0.0.1:2423/api/v1/cluster/edit/promotion_rule"

Edit access level

Description: Edit the access level for the primary.

Endpoint: cluster/edit/access_level

Method: PUT

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB

  • flag: Option to change the access level for the primary. Options:

    • rw: Primary will be open to receive wrtie and read traffic.
    • w: Primary will be open to write traffic only.
{
  "name": "europe-80-01",
  "flag": "w"
}

Output:

  • 0:.- OK: access level changed and effective

  • 1.- ERROR: The indicated cluster does not exists. Error in cluster name

  • 2.- ERROR: Flag is not valid. Accepted values for access level are w (Write only) or rw (Read & write)

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu", "flag": "w"}' "http://127.0.0.1:2423/api/v1/cluster/edit/access_level"

Node

Remove

Description: Remove a given replica by Id (Get teh instance_id from cluster/info API call). It doesn't work to remove a primary

Endpoint: node/remove

Method: DELETE

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB

  • node_id: Unique identifier for the replica to remove. You can take this value from the cluster/details API call.

{
  "name": "mysql8-eu",
  "node_id": 3
}

Output:

  • 0:.- OK: Replica node removed. Note that if the replcia is still alive and replicating from the primary Gonarch will automatically include it again.

  • 1.- ERROR: The indicated cluster does not exists. Error in cluster name

  • 2.- ERROR: The indicated replica node does not exists or it's not a replica.

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu", "node_id": 3}' "http://127.0.0.1:2423/api/v1/cluster/node/remove"

Edit backup role

Description: Mark any replica as backup. This will flag teh node as non promotable and will stop serving traffic. If you ran this call against a replica it will switch to backup. If the replica is already running as backup node it will switch back to replica role.

Endpoint: /node/edit/role/backup

Method: PUT

Parameters:

  • name: Cluster name. Identifier to elminate the cluster and any related metadata in the backend DB

  • node_id: Unique identifier for the replica to change. You can take this value from the cluster/details API call.

{
  "name": "mysql8-eu",
  "node_id": 3
}

Output:

  • 0:.- OK: Replica role set to replica. From now on this replica can be promoted and will serve traffic as usual. / Replica role set to backup. From now on this replica cannot be promoted and won't serve any traffic

  • 1.- ERROR: The indicated cluster does not exists. Error in cluster name

  • 2.- ERROR: The indicated replica node does not exists or it's not a replica.

Example:

$> curl -X PUT -H "Content-Type: application/json" -d '{"name": "mysql8-eu", "node_id": 3}' "http://127.0.0.1:2423/api/v1/node/edit/role/backup"

Clone this wiki locally