[occi-wg] Semantics of OCCI API: nouns and verbs

[Chris Webb]

The single strongest point we want to make is that an API should be simple.

We're convinced that an API covering infrastructure can be formulated on a
handful of straightforward objects with no more than around fifteen or
twenty operations in total.

We're also convinced that these operations can be very simple and
straightforward, with syntax which could easily be typed by hand, but this
is a later issue once we agree on the nouns and verbs themselves.

In the spirit of 'put up or shut up', here's a suggestion of what the
complete set of nouns and verbs might be, based on what we have in our
existing API.

Nouns:

  drives - block devices to attach to virtual machines. The general case
  here is clearly behaviour like Amazon EBS - drives are persistent and
  exist independently of virtual machines. A virtual machine can mount
  several drives, and conversely a drive (like a CD image) can in principle
  be mounted from several virtual machines. GoGrid 'one drive per server'
  behaviour is clearly a subset of this, and Amazon's filesystem initialised
  from an AMI at boot can be represented by throwaway copies of a drive (or
  copy-on-write) instead of writing back to the drive.

  resources - things like static IP addresses and VLANs which need to be
  reserved for use by virtual machines.

  guests - virtual servers booted from and accessing drives. Our guests
  exist as objects only when they are running, similar to Amazon's
  instances, but it may be more general to allow guests in stopped and
  suspended states in addition, as GoGrid currently do.


Verbs:

  drives
    list (list accessible drives)
    ---
    info (list drive properties)
    create (takes properties including size; give parent drive for snapshot)
    destroy (delete existing drive)
    set (takes properties including size to resize)
    read (read data of given size with given offset in drive)
    write (write data at given offset in drive)
    image (copy data from one drive to another)

  resources
    list (list allocated resources)
    ---
    info (detail on an allocated resource)
    create (to allocate a resource such as a static IP address)
    destroy (to release a resource)


  guests
    list (list virtual machines)
    ---
    info (list virtual machine properties)
    create (takes simple description, e.g. including attached drives and
            network interfaces)
    set (updates configuration from new description where possible)
    destroy (hard-kill virtual machine)
    reset (send reset to virtual machine)
    shutdown (gracefully shut down virtual machine)
    [perhaps also stop, start, suspend for stopped guests?]

Does anyone think we've missed anything?


Comparison with draft API on the wiki
=====================================

The draft API on the OCCI wiki currently appears to offer nouns for servers,
storage devices, network interfaces with the ability to create, retrieve,
update and delete any noun and 6 verbs for machine control.

Our suggestion above is very similar, but more explicit and descriptive. In
particular:

  - list, info, create, destroy, set are equivalent to CRUD;
  - added drive operations: read, write, image
  - resize operation handled by passing the new size to drive set;
  - nouns for network resources (e.g. static IPs, VLANs) rather than network
    interfaces[1];
  - similar set of machine operations, assuming we want to handle stopped
    guests.

[1] We believe that interfaces are simply one aspect of a server's
configuration, and that the nouns that matter are the objects such as static
IPs which are "owned" by a customer and hence can be configured onto the
server.

Cheers,

Chris.