Include versioning information in plugin APIs

[jasmingacic]

We are about to publish two infrakit third party plugins. We were wondering how to tie our plugins to a specific release or revision?

To be more specific for example recently you changed infrakit group watch to commit. Having a plugin tutorial might look incorrect after a change.

Also since plugins implement instance.Plugin do you plan to change the interface sometimes in the future?

[chungers]

I've added this Issue to our v0.1.0 milestone requirement. Some key points:

1. The JSON-RPC API and its versioning
2. Handshake / metadata
3. Documentation and consistency

• While the golang API / library are useful for building plugins, JSON-RPC over HTTP is the official API for the plugins.
• Several pull requests were merged to address the points above: Use JSON-RPC over HTTP for communication between plugins #297 Add HTTP request debug logging #300 for 1 and 2; Introduce a check that links that source files with documentation about them #307 for 3.
• Before the final v0.1.0 let's add a metadata / plugin activation RPC method, since JSON-RPC over HTTP specs ( here and here ) on their own do not specify means for API versioning.
• The metadata RPC method can inspiration from the Docker plugin API Handshake API -- proposal below.

Metadata / Handshake API

This design is inspired by the handshake api
for Docker plugins:

• Each plugin will implement a new RPC method /Plugin.Meta which will accept a HTTP POST with empty body and returns

 { "Implements": [ "Instance/0.1" ] }

Notes

• A plugin can implement multiple interfaces (note the array)
• There may be additional fields in this struct which will give example request / response structs (Design TBD - will update in this thread).

[wfarner]

There may be additional fields in this struct which will give example request / response structs

I'd like to suggest that we peel the above off as a separate issue/effort, and not make it a blocker for 0.1.0. It's nice to have, but i think it is non-critical for a release.