Design of

Compass REST API

and DB Schema

Grace Yu

Agenda

RESTful API

• API versioning (URL)
• HTTP PATCH method (vs PUT)

Database

• Data Access Object
• OS/Package Config schema

RESTful APIs

• Remain the same as before (on a high level)
• Detailed design available in separate docs
• Previous API reference doc

Resources

• Adapters
• Switches
• Machines
• Clusters
• Hosts
• ClusterHosts
• Users

New: API Versioning

GET /api/v1.0/clusters/1

• Prepare for future API version transition
• Use Flask Blueprint feature
  • A framework for modular components within Flask

Blueprint

from flask import Blueprint
from flask.ext.restful import Api

v1 = Blueprint('v1_app', __name__)
api = Api(v1)

from compass.api.v1.api import v1_app as v1

app = Flask(__name__)
app.register_blueprint(v1, url_prefix="/v1.0")

New: PATCH support

• PUT: Update a full new resource represention
• PATCH: Update a resourse's partial (delta) representation

Example

{
"os_config" : {
  "networking" : {
    "eth0" : {
      // Note: this is full attribute spec.
      "ip_address" : "192.168.1.200",
      "netmask" : "255.255.255.0",
      "gateway" : "192.168.1.10"
    }
  }
 }
}

{
"os_config" : {
  "networking" : {
    "eth0" : {
      // Note: this is a partial update
      // So we use PATCH method.
      "ip_address" : "192.168.1.203"
    }
  }
 }
}

Data Access Object

• Encapsulate database layer
• Implements data layer business logic
• API layer does not access database directly

Config Metadata

• Describe OS/package configuration information
• Use a tree hierarchy
• Stored in a SQL table using adjacency list pattern
• Config fields are stored only in leaf nodes

• os-config
  • networking
    • $interface
      • ip_address
      • netmask
      • gateway
    • server_credentials
      • username
      • password
• package-config

Config Data Field

• name
• type
• validator
• is_required?
• description

Why Metadata?

• Support configuration extension through data-driven APIs
• Generic handling of data validation, data storage and access
• Extension can be dynamically loaded through plugin modules

Demo

THE END

Questions?

Dreams