fleet/Documentation/examples/api.py

api.py

#
# This file provides an example of a very simple client library written in Python.
# The client builds an interface for interacting with the fleet API, then retrieves
# a list of Units currently loaded into fleet.
#
# Warning: the code below is a significally simplified version of a typical client
# library. It is an incomplete implementation that is provided to demonstrate
# some aspects of building a client library. It is not production-ready code.
#
# This example assumes that fleet is configured to listen on localhost:8080
#
# Requirements:
#  httplib2 - https://github.com/jcgregorio/httplib2
#  uritemplate - https://github.com/uri-templates/uritemplate-py
#
import httplib2
import json
import uritemplate
import urllib
import urlparse
import pprint

# Step 1: Fetch Discovery document.
ROOT_URL = "http://localhost:8080/"
DISCOVERY_URI = ROOT_URL + "fleet/v1/discovery"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URI = ROOT_URL + discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urlparse.urljoin(BASE_URI, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).iteritems():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).iteritems():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).iteritems():
    setattr(collection, name, createNewMethod(name, method))
  return collection

service = build(discovery, Collection())

# Step 3.b: Use the client
response = service.Machines.List()

# output metadata (status, content-length, etc...)
pprint.pprint(response[0])

# output body
pprint.pprint(json.loads(response[1]))

DEVNOTES.md

See also

• API Discovery Service
• https://github.com/coreos/fleet/blob/master/Documentation/api-v1.md#capability-discovery

v1.json

{
  "kind": "discovery#restDescription",
  "discoveryVersion": "v1",
  "id": "fleet:v1",
  "name": "schema",
  "version": "v1",
  "title": "fleet API",
  "description": "",
  "documentationLink": "http://github.com/coreos/fleet",
  "protocol": "rest",
  "icons": {
    "x16": "",
    "x32": ""
  },
  "labels": [],
  "baseUrl": "$ENDPOINT/fleet/v1/",
  "basePath": "/fleet/v1/",
  "rootUrl": "$ENDPOINT/",
  "servicePath": "fleet/v1/",
  "batchPath": "batch",
  "parameters": {},
  "auth": {},
  "schemas": {
    "Machine": {
      "id": "Machine",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "primaryIP": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "properties": {},
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "MachinePage": {
      "id": "MachinePage",
      "type": "object",
      "properties": {
        "machines": {
          "type": "array",
          "items": {
            "$ref": "Machine"
          }
        },
        "nextPageToken": {
          "type": "string"
        }
      }
    },
    "UnitOption": {
      "id": "UnitOption",
      "type": "object",
      "properties": {
        "section": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "Unit": {
      "id": "Unit",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "UnitOption"
          }
        },
        "desiredState": {
          "type": "string",
          "enum": [
            "inactive",
            "loaded",
            "launched"
          ]
        },
        "currentState": {
          "type": "string",
          "enum": [
            "inactive",
            "loaded",
            "launched"
          ]
        },
        "machineID": {
          "type": "string",
          "required": true
        }
      }
    },
    "UnitPage": {
      "id": "UnitPage",
      "type": "object",
      "properties": {
        "units": {
          "type": "array",
          "items": {
            "$ref": "Unit"
          }
        },
        "nextPageToken": {
          "type": "string"
        }
      }
    },
    "UnitState": {
      "id": "UnitState",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "hash": {
          "type": "string"
        },
        "machineID": {
          "type": "string"
        },
        "systemdLoadState": {
          "type": "string"
        },
        "systemdActiveState": {
          "type": "string"
        },
        "systemdSubState": {
          "type": "string"
        }
      }
    },
    "UnitStatePage": {
      "id": "UnitStatePage",
      "type": "object",
      "properties": {
        "states": {
          "type": "array",
          "items": {
            "$ref": "UnitState"
          }
        },
        "nextPageToken": {
          "type": "string"
        }
      }
    }
  },
  "resources": {
    "Machines": {
      "methods": {
        "List": {
          "id": "fleet.Machine.List",
          "description": "Retrieve a page of Machine objects.",
          "httpMethod": "GET",
          "path": "machines",
          "parameters": {
            "nextPageToken": {
              "type": "string",
              "location": "query"
            }
          },
          "response": {
            "$ref": "MachinePage"
          }
        }
      }
    },
    "Units": {
      "methods": {
        "List": {
          "id": "fleet.Unit.List",
          "description": "Retrieve a page of Unit objects.",
          "httpMethod": "GET",
          "path": "units",
          "parameters": {
            "nextPageToken": {
              "type": "string",
              "location": "query"
            }
          },
          "response": {
            "$ref": "UnitPage"
          }
        },
        "Get": {
          "id": "fleet.Unit.Get",
          "description": "Retrieve a single Unit object.",
          "httpMethod": "GET",
          "path": "units/{unitName}",
          "parameters": {
            "unitName": {
              "type": "string",
              "location": "path",
              "required": true
            }
          },
          "parameterOrder": [
            "unitName"
          ],
          "response": {
            "$ref": "Unit"
          }
        },
        "Delete": {
          "id": "fleet.Unit.Delete",
          "description": "Delete the referenced Unit object.",
          "httpMethod": "DELETE",
          "path": "units/{unitName}",
          "parameters": {
            "unitName": {
              "type": "string",
              "location": "path",
              "required": true
            }
          },
          "parameterOrder": [
            "unitName"
          ]
        },
        "Set": {
          "id": "fleet.Unit.Set",
          "description": "Create or update a Unit.",
          "httpMethod": "PUT",
          "path": "units/{unitName}",
          "parameters": {
            "unitName": {
              "type": "string",
              "location": "path",
              "required": true
            }
          },
          "parameterOrder": [
            "unitName"
          ],
          "request": {
            "$ref": "Unit"
          }
        }
      }
    },
    "UnitState": {
      "methods": {
        "List": {
          "id": "fleet.UnitState.List",
          "description": "Retrieve a page of UnitState objects.",
          "httpMethod": "GET",
          "path": "state",
          "parameters": {
            "nextPageToken": {
              "type": "string",
              "location": "query"
            },
            "unitName": {
              "type": "string",
              "location": "query"
            },
            "machineID": {
              "type": "string",
              "location": "query"
            }
          },
          "response": {
            "$ref": "UnitStatePage"
          }
        }
      }
    }
  }
}