Cue/api1vsapi2

API Approach 1 Vs API Approach 2
This page will analyze the comparison between the two main API approaches for project Cue.

The first approach is located here: https://wiki.openstack.org/wiki/Cue/api

The second approach is located here: https://wiki.openstack.org/wiki/Cue/api_2

API Approach 1 Summary
The first approach to the API provides more visibility on the inner structures and configuration of the messaging clusters deployed by Cue. This exposure would allow the user additional control on a per-node configuration before and after cluster deployment. This lends to a more hands-on deployment and configuration structure allowing the user finer level control. On the other hand, this can lead to miss-configured and unstable clusters.

When the user creates a new cluster (POST), the API accepts the general cluster settings and a list of "nodes" which currently only contains VM flavor (e.g. small, medium, large). The reasoning to accept a node list of flavors even though it only makes sense to have all nodes in a cluster be the same flavor is with respect to consistency with the JSON response. The response body contains the same structure as the request body, where the nodes list now holds additional information about the nodes in the new cluster (e.g. node id, status, flavor..). The overall API is well positioned to expose full node by node control of Messaging clusters for the user. For a cluster update, the user can specify exactly which node to update, add or remove.

API Approach 2 Summary
The second approach to the API hides per-node details in a cluster. The API accepts configuration settings for a cluster as a whole, for example flavor and size which denote the overall node flavor and number of nodes respectively. This design minimizes internal per-node configuration and therefore lends to a messaging deployment system that will automate the full deployment process with minimal user intervention and therefore reducing possible user related errors.

An update to a cluster is issued by changing cluster-level parameters such as size or flavor. For example, Cue decides which node(s) to remove in the case of a down-size.

Extending to Custom Messaging Cluster Configurations
The main goal of Cue is to provide users a simple, efficient, reliable and HA cluster messaging provisioning/maintenance service. The user-facing API should therefore allow for simple deployment of mainstream messaging clusters, while at the same time allow for the provisioning of custom (node-level) user define clusters.

One possible approach is to keep the API configurable at the cluster-level, and allow a user-specified link to a custom configuration template file. The configuration template file would allow the user to define fine grain cluster/node configuration. There would be a configuration template file format for each supported messaging technology (e.g. RabbitMQ, Kafka, Qpid, etc..). If the user does not provide an input configuration template file, Cue would use a pre-define template file for the given messaging technology.

This would allow the mainstream user without in-depth messaging technology knowledge the ability to quickly/easily deploy their messaging cluster, and allow power users to deploy fully customizable clusters as per specified configurations.

In summary:
 * Simple API to deploy cluster-level configurable messaging clusters
 * API can accept an optional template configuration file for full node-level configuration
 * One template configuration file per messaging technology supported
 * Default template configuration file is used by Cue when one is not provided through API

Questions/discussions:

 * 1) Where do users acquire the configuration template files from?
 * 2) How do users know which endpoint is up/down with the second approach?