apiary.apib

# GoSLB API

GoSLB server has two REST API groups: Services API and Cat API. Services API is used
to configure the services (DNS records). Cat API is a read-only API used for querying
the current state in a CLI friendly format.

# Service object fields

  * **Domain** [string]: Fully qualified domain name of the service
  * **Endpoints:** [Endpoint]: List of Endpoint objects
  * **Monitor** [Monitor]: Health monitor configuration for the service endpoints

  
# Endpoint object fields

  * **IP** [string]: Endpoint IP address
  * **Enabled** [boolean]: If false, endpoint is disabled: not monitored and not returned in any DNS 
                           replies
  * **Priority** [number]: Endpoint's priority. From the enabled, healthy endpoints, only those with
                           highest priority are returned
  * **Site** [string]: Site the endpoint belongs to. Clients are assigned a site based on IP ranges on
                       every request. Endpoints in client's local site are preferred over other sites.


# Monitor object fields

  * **Type** [string]: Either TCP or HTTP
  * **Interval** [number]: Monitor execution interval in seconds
  * **Timeout** [number]: Monitor execution timeout in seconds 
  * **Port** [number]: TCP port to probe

**HTTP monitor extra fields:**

  * **URI** [string]: HTTP URI to fetch
  * **SuccessCodes** [number]: List of HTTP status codes that are considered success
    

# Group Services API

Manage services, endpoints and health monitors.

## Service collection [/services/]

### List all services [GET]

+ Response 200 (application/json)

        [
            "foo.goslb.",
            "bar.goslb."
        ]

### Create a New Service [POST]

+ Request (application/json)

        {
            "Domain": "foo.goslb.",
            "Endpoints": [
                {
                    "IP": "127.0.0.1", 
                    "Enabled": true,
                    "Priority": 0,
                    "Site": "london"
                },
                {
                    "IP": "172.31.1.31",
                    "Enabled": true,
                    "Priority": 0,
                    "Site": "prague"
                }
            ],
            "Monitor": {
                "Type": "TCP",
                "Interval": 10,
                "Timeout": 2,
                "Port": 80
            }
        }

+ Response 201 (application/json)

    + Headers

            Location: /services/foo.goslb.

    + Body

            {
                "Success":true
            }

## Service [/services/{service}]

+ Parameters
    + service (required, string, `foo.goslb.`) ... Service fully-qualified domain name

### Retreive a Service configuration [GET]

+ Response 200 (application/json)

        {
            "Domain": "foo.goslb.",
            "Endpoints": [
                {
                    "IP": "127.0.0.1",
                    "Enabled": true,
                    "Priority": 0,
                    "Site": "london",
                    "Healthy": true
                },
                {
                    "IP": "172.31.1.31",
                    "Enabled": true,
                    "Priority": 0,
                    "Site": "prague",
                    "Healthy": true
                }
            ],
            "Monitor": {
                "Type": "TCP",
                "Interval": 10,
                "Timeout": 2,
                "Port": 80,
                "Uri": "",
                "SuccessCodes": null
            }
        }

### Update a Service [PUT]

+ Request (application/json)

        {
            "Domain": "foo.goslb.",
            "Endpoints": [
                {
                    "IP": "127.0.0.1",
                    "Enabled": false,
                    "Site": "london",
                },
                {
                    "IP": "172.31.1.31",
                    "Enabled": true,
                    "Site": "prague",
                }
            ],
            "Monitor": {
                "Type": "TCP",
                "Interval": 10,
                "Timeout": 2,
                "Port": 8080,
            }
        }

+ Response 200 (application/json)

        {
            "Success": true
        }
        
### Delete a Service [DELETE]

+ Response 200 (application/json)

        {
            "Success": true
        }


# Group _cat API

The cat API (thanks Elasticsearch for the idea) is a simple read-only API for 
human interaction. It shows the information in text tabular format, parseable
by standard cli tools.

## Endpoints [/_cat/endpoints/{service}]

+ Parameters
    + service (required, string, `foo.goslb.`) ... Service fully-qualified domain name

### Retrieve Endpoints' status [GET]

+ Response 200 (text/plain)

        IP          Enabled Healthy Priority Site
        127.0.0.1   true    false   0        london
        172.31.1.31 true    false   0        prague

## Client Site [/_cat/clientsite]

### Retrieve Client Site [GET]

Returns what site the API cient belongs to (based on the client IP)

+ Response 200 (text/plain)

        127.0.0.1: london