Add documentation for plugin HTTP APIs

docs/plugins/README.md

@@ -102,3 +102,32 @@ project, so please double-check where the code lives before filing InfraKit issu
 | [docker/infrakit.aws](https://github.com/docker/infrakit.aws) | instance | creates Amazon EC2 instances                          |
 
 Have a Plugin you'd like to share?  Submit a Pull Request to add yourself to the list!
+
+### APIs
+_InfraKit_ plugins are exposed via HTTP, using [JSON-RPC 2.0](http://www.jsonrpc.org/specification).
+
+API requests can be made manually with `curl`.  For example, the following command will list all groups:
+```console
+$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \
+  -H 'Content-Type: application/json'
+  -d '{"jsonrpc":"2.0","method":"Group.InspectGroups","params":{},"id":5577006791947779410}'
+{"jsonrpc":"2.0","result":{"Groups":null},"id":1}
+```
+
+API errors are surfaced with the `error` response field:
+```console
+$ curl -X POST --unix-socket ~/.infrakit/plugins/group http:/rpc \
+  -H 'Content-Type: application/json'
+  -d '{"jsonrpc":"2.0","method":"Group.CommitGroup","params":{},"id":1}'
+{"jsonrpc":"2.0","error":{"code":-32000,"message":"Group ID must not be blank","data":null},"id":1}
+```
+
+Per the JSON-RPC format, each API call has a `method` and `params`.  The following pages define the available methods
+for each plugin type:
+- [Flavor](flavor.md)
+- [Group](group.md)
+- [Instance](instance.md)
+
+See also: documentation on common API [types](types.md).
+
+Additionally, all plugins will log each API HTTP request and response when run with the `--log 5` command line argument.

docs/plugins/flavor.md

@@ -0,0 +1,144 @@
+# Flavor plugin API
+
+<!-- SOURCE-CHECKSUM pkg/spi/flavor/* 81a2c81f42a56ce0baa54511ee621f885fc7080e -->
+
+## API
+
+### Method `Flavor.Validate`
+Checks whether a Flavor configuration is valid.
+
+#### Request
+```json
+{
+  "Properties": {},
+  "Allocation": {
+    "Size": 1,
+    "LogicalIDs": ["logical_id_1"]
+  }
+}
+```
+
+Parameters:
+- `Properties`: A JSON object representing the Flavor.  The schema is defined by the Flavor plugin in use.
+- `Allocation`: An [Allocation](types.md#allocation)
+
+
+#### Response
+```json
+{
+  "OK": true
+}
+```
+
+`OK`: Whether the operation succeeded.
+
+### Method `Flavor.Prepare`
+Instructs the Flavor Plugin to prepare an Instance with any additional configuration it wishes to include.  The Flavor
+may add, remove, or modify any fields in the Instance `Spec` by returning the desired Instance configuration.
+
+#### Request
+```json
+{
+  "Properties": {},
+  "Spec": {
+    "Properties": {},
+    "Tags": {
+      "tag_key": "tag_value"
+      },
+    "Init": "init script",
+    "LogicalID": "logical_id",
+    "Attachments": ["attachment_id"]
+  },
+  "Allocation": {
+    "Size": 1,
+    "LogicalIDs": ["logical_id_1"]
+  }
+}
+```
+
+Parameters:
+- `Properties`: A JSON object representing the Flavor.  The schema is defined by the Flavor plugin in use.
+- `Spec`: The [Spec](types.md#instance-spec) of the Instance being prepared.
+- `Allocation`: An [Allocation](types.md#allocation)
+
+#### Response
+```json
+{
+  "Spec": {
+    "Properties": {},
+    "Tags": {
+      "tag_key": "tag_value"
+      },
+    "Init": "init script",
+    "LogicalID": "logical_id",
+    "Attachments": ["attachment_id"]
+  }
+}
+```
+
+Fields:
+- `Spec`: The [Spec](types.md#instance-spec) of the Instance, with the Flavor's adjustments made.
+
+### Method `Flavor.Healthy`
+Checks whether the Flavor plugin considers an Instance to be healthy.
+
+#### Request
+```json
+{
+  "Properties": {},
+  "Instance": {
+    "ID": "instance_id",
+    "LogicalID": "logical_id",
+    "Tags": {
+      "tag_key": "tag_value"
+    }
+  }
+}
+```
+
+Parameters:
+- `Properties`: A JSON object representing the Flavor.  The schema is defined by the Flavor plugin in use.
+- `Instance`: The [Instance Description](types.md#instance-description)
+
+#### Response
+```json
+{
+  "Health": 1
+}
+```
+
+Fields:
+- `Health`: An integer representing the health the instance. `0` for 'unknown', `1` for 'healthy', or `2' for
+  'unhealthy'
+
+### Method `Flavor.Drain`
+Informs the Flavor plugin that an Instance will soon be terminated, and allows the plugin to perform any necessary
+cleanup work prior to removing the instance.
+
+#### Request
+```json
+{
+  "Properties": {},
+  "Instance": {
+    "ID": "instance_id",
+    "LogicalID": "logical_id",
+    "Tags": {
+      "tag_key": "tag_value"
+    }
+  }
+}
+```
+
+Parameters:
+- `Properties`: A JSON object representing the Flavor.  The schema is defined by the Flavor plugin in use.
+- `Instance`: The [Instance Description](types.md#instance-description)
+
+#### Response
+```json
+{
+  "OK": true
+}
+```
+
+Fields:
+- `OK`: Whether the operation succeeded.

docs/plugins/group.md

@@ -0,0 +1,140 @@
+# Group plugin API
+
+<!-- SOURCE-CHECKSUM pkg/spi/group/* 0eec99ab5b4dc627b4025e29fb97dba4ced8c16f -->
+
+## API
+
+### Method `Group.CommitGroup`
+Submits the configuration for a group.  The Group plugin is responsible for making any changes necessary to effect the
+configuration.
+
+#### Request
+```json
+{
+  "Spec": {
+    "ID": "group_id",
+    "Properties": {}
+  },
+  "Pretend": true
+}
+```
+
+Parameters:
+- `Spec`: A [Group Spec](types.md#group-spec)
+- `Pretend`: Whether to actually perform the change.  If `false`, the request will have no side-effects.
+
+#### Response
+```json
+{
+  "Details": "human readable text"
+}
+```
+
+Fields:
+- `Details`: A human-readable description of the commit action, or proposed action if `Pretend` was `true`.
+
+
+### Method `Group.FreeGroup`
+Removes a Group from active management.  This operation is non-destructive - it will not destroy or modify any resources
+associated with the Group.  However, the Plugin will no longer attempt to maintain the state of the Group.
+
+#### Request
+```json
+{
+  "ID": "group_id"
+}
+```
+
+Parameters:
+- `ID`: [Group ID](types.md#group-id)
+
+#### Response
+```json
+{
+  "OK": true
+}
+```
+
+Fields:
+- `OK`: Whether the operation succeeded.
+
+### Method `Group.DescribeGroup`
+Fetches details about the current status of a Group.
+
+#### Request
+```json
+{
+  "ID": "group_Id"
+}
+```
+
+Parameters:
+- `ID`: [Group ID](types.md#group-id)
+
+#### Response
+```json
+{
+  "Description": {
+    "Instances": [
+      {
+        "ID": "instance_id",
+        "LogicalID": "logical_id",
+        "Tags": {
+          "tag_key": "tag_value"
+        }
+      }
+    ],
+    "Converged": true
+  }
+}
+```
+
+Fields:
+- `Description`: A [Group Description](types.md#group-description)
+
+### Method `Group.DestroyGroup`
+
+#### Request
+```json
+{
+  "ID": "group_Id"
+}
+```
+
+Parameters:
+- `ID`: [Group ID](types.md#group-id)
+
+#### Response
+```json
+{
+  "OK": true
+}
+```
+
+Fields:
+- `OK`: Whether the operation succeeded.
+
+### Method `Group.InspectGroups`
+Fetches details about the state associated with a Group.
+
+#### Request
+```json
+{}
+```
+
+Parameters: None
+
+#### Response
+```json
+{
+  "Groups": [
+    {
+      "ID": "group_id",
+      "Properties": {}
+    }
+  ]
+}
+```
+
+Fields:
+- `Groups`: An array of [Group Specs](types.md#group-spec)