ReST API

Overview

The main communication interface with GlusterD-2.0 (GD2) is the HTTP ReST interface. This interface will be made use of by the GD2 CLI, and will also be available for external consumers to use.

GD2 will provide ReST interfaces for the management of peers, management of volumes, local-GlusterD management, interfaces for monitoring (events) and possible long-running asynchronous operations.

Authentication

The API will use a stateless authentication model using JSON web tokens. This will be based on the Heketi authentication model.

This is still tentative

API

NOTE: These APIs are incomplete.

This is the first version of the GD2 ReST API, APIVERSION is 1. All the endpoints defined below will be prefixed with /v<API_VERSION> unless otherwise mentioned. While this page talks about the basic peer and volume management APIs in detail, the rest of the API endpoints and their details can be found here.

GD2 uses JSON as its data serialization format.

Most APIs use the following methods on the URIs:

URIs in the form of /<version>/<ReST endpoint>/{id}
Requests and responses in JSON format
POST: Send data to GD2 where the body has data described in JSON format.
GET: Retrieve data from GD2 where the body has data described in JSON format.
DELETE: Deletes the specified object from GD2.
The HTTP content-type for all requests and responses will be application/json.

Peers

The peers endpoint will be used to manage peers in the cluster. All peers endpoints will have the prefix /peers/.

Attach peer

Method : POST
Endpoint : /peers
Request :
- Parameters : None
- Body:
  - addresses : An array of strings. Gives a list of addresses by which the new host can be contacted. The addresses can be FQDNs, short-names or IP addresses. At least 1 address is required.
  - Example :

{
    "addresses": [
        "host1name1",
        "host1name2"
    ]
}

Response :
- Status code: 201 Created
- Body:
  - id : A string. The UUID of the newly added peer
  - Example :

	{ "id" : "de305d54-75b4-431b-adb2-eb6b9e546014"}

Get peer

Method : GET
Endpoint : /peers/{id}
Request:
- Parameters :
  - id : UUID of the peer or the name of the peer to get.
- Body : Empty
Response:
- Status code: 200 OK
- Body :
  - id : A string. The UUID of the peer
  - name : A string. The name of the peer.
  - addresses : An array of strings. Each entry in the list is an address by which the peer can be connected to.
  - online : A boolean. Gives online status of the peer
  - Example :

{
    "id": "c1cf34e2-5bb7-4885-b8c2-0d92199993f9",
    "name": "peer2",
    "addresses": [
      "p2a1",
      "p2a2",
      "p2a3"
    ],
    "online": true
}

List peers

Method : GET
Endpoint : /peers
Request:
- Parameters : None
- Body : Empty
Response:
- Status code : 200 OK
- Body : An array of peer information JSON objects. For details of the peer information object refer Get peer.

Detach peer

Method : DELETE
Endpoint: /peers/{id}
Request:
- Parameters :
  - id : Name or ID of peer to be detached from the cluster
- Body : Empty
Response:
- Status code : 204 No Content
- Body : Empty

Volumes

The volumes endpoints will be used to manage volumes in the cluster. All volumes endpoints have the prefix /volumes/

Create volume

Method : POST
Endpoint: /volumes
Request:
- Parameters : None
- Body :
  - name : A string. Name of the volume
    - subvols : List of sub volumes
    - transport : A string, optional. Represents the transport type (TCP/RDMA/Both). Default to be TCP
  - flags : A JSON object with string-boolean key-value pairs, optional. The keys are flags and the values are their state. The default value is false.

Available flags

      - "reuse_bricks"
      - "allow_root_dir"
      - <need to add others we introduce>

Each sub volume can have following fields

- *type* : Sub volume Type, "replicate", "distribute", "disperse" etc
- *stripe* :  An integer, optional. Represents the stripe count for a stripe volume
- *replica* : An integer, optional. Represents the replica count for a replicate volume. Default to be 1
- *arbiter* : An integer, optional. Represents the arbiter count for an arbiter volume
- *disperse-count* : An integer, optional. Represents the disperse-count for a dispersed volume
- *disperse-data* : An integer, optional. Represents the disperse-data count for a dispersed volume
- *disperse-redundancy* : An integer, optional. Represents the redundancy count for a dispersed volume
- *bricks* : An array of brick object. Holds list of bricks to be configured for the sub volume.

brick object can have following fields:

- *nodeid* : Node ID
- *path* : Brick directory path
- *type* : Optional, To be specified if not default brick type, Example "arbiter"

Example :

{
    "name": "test-vol",
    "subvols": [
        {
            "type": "replicate",
            "replica": 2,
            "bricks": [
                {"nodeid": "1aa7ee28-174e-42d0-8337-41cc1702db89", "path": "/home/bricks/b1"},
                {"nodeid": "43127542-71e4-4e17-8ac2-aaa8a910b806", "path": "/home/bricks/b2"}
            ]
         }
    ],
    "force": true
}

Response:
- Status code : 201
- Body : A JSON object of a volume. For details please refer Get volume

Get volume

Method : GET
Endpoint: /volumes/{id}
Request:
- Parameters :
  - id : ID of the volume. The name of the volume is also accepted.
- Body : Empty
Response:
- Status code: 200 OK
- Body :
  - id : A string. UUID of the volume
  - name : A string. Name of the volume
  - type : A string. Type of the volume which is any of the following
    - Distribute
    - Stripe
    - Striped-Replicate
    - Disperse
    - Tier
    - Distributed-Stripe
    - Distributed-Replicate
    - Distributed-Striped-Replicate
    - Distributed-Disperse
  - stripe : An integer. Represents the stripe count for a stripe volume
  - replica : An integer. Represents the replica count for a replicate volume
  - arbiter : An integer. Represents the arbiter count for an arbiter volume
  - transport : A string, transport type of the volume
  - options : A map of key value strings. Represents volume tunables
  - status : A string. Status of the volume either "Created" or "Started" or "Stopped"
  - version : An integer. Version of the volume, internal to GlusterD
  - checksum : An integer. md5 checksum value of the volume configuration, internal to GlusterD
  - bricks : An array of strings. Represents each brick with following details:
    - id : A string. UUID of the peer to which this brick belongs
    - hostname : A string. Host/IP of the brick
    - path : A string. Path of the brick
  - Example :

{
    "id": "0bef87b3-82ba-11e5-9d59-3c970e9eb10d",
    "name": "test-vol",
    "type": "Distribute",
    "stripe": 0,
    "replica": 0,
    "arbiter": 0,
    "transport": "TCP",
    "options": {},
    "status": "Created",
    "checksum": 12345,
    "version": 1,
    "bricks": [
        {
            "id": "e5c26603-82bf-11e5-9d59-3c970e9eb10d",
            "hostname": "x.x.x.x",
            "path": "/gluster/brick1",
        },
        {
            "id": "06c47cc3-82c0-11e5-9d59-3c970e9eb10d",
            "hostname": "y.y.y.y",
            "path": "/gluster/brick2",
        }
    ]
}

Get volumes

Method : GET
Endpoint: /volumes
Request :
- Parameters : None
- Body : Empty
Response :
- Status code : 200 OK
- Body : A string-string JSON map, with volume-id as key and volume name as value.
- Example :

{
  "0bef87b3-82ba-11e5-9d59-3c970e9eb10d": "test-vol",
  "eb6aaea1-1689-4a45-8dbf-d4c98f76d9c5": "vol1"
}

Start volume

Method : POST
Endpoint: /volumes/{name}/start
Request :
- Parameters :
  - name: Name of the volume
- Request body : Empty
Response :
- Status code : 200 OK
- Response body : Empty

Stop volume

Method : POST
Endpoint: /volumes/{name}/stop
Request :
- Parameters :
  - name : Name or ID of volume
- Body : Empty
Response :
- Status code : 200 OK
- Body : Empty

Delete volume

Method : DELETE
Endpoint: /volumes/{name}
Request :
- Parameters :
  - name : Name of the volume
- Body : Empty
Response :
- Status code : 204 No Content
- Body : Empty

Create option group

Method : POST
Endpoint : /volumes/options-group
Request:
- Parameters : None
- Body :
  - name : A string. Name of the group to be created
  - options : List of options. Each option must have a name and two values corresponding to the profile being set or unset
  - Example :

{
        "name" : "profile.sample",
        "options" : [{"name": "afr.eager-lock", "onvalue":"on", "offvalue": "off"}]
}

Response:
- Status code : 201
- Body : A JSON object representing the newly created option group

Delete option group

Method : DELETE
Endpoint: /volumes/options-group/{name}
Request :
- Parameters :
  - name : Name of the group
- Body : Empty
Response :
- Status code : 200 OK
- Body : Empty

List option groups

Method : GET
Endpoint: /volumes/options-group
Request :
- Parameters : None
- Body : Empty
Response :
- Status code : 200 OK
- Body : A list of all groups currently in the store

Provide feedback

Saved searches

Use saved searches to filter your results more quickly