On Mon, Jun 18, 2012 at 11:02:25AM -0400, Saggi Mizrahi wrote:
> The first thing we need to decide is API supportabiliy. I'll list the 
> questions
> that need to be answered. The decision made here will have great effect on
> transport selection (espscially API change process and versioning) so try and
> think about this without going to specfic technicalities (eg. "X can't be done
> on REST").

Thanks for sending this out.  I will take a crack at these questions...

I would like to pose an additional question to be answered:

- Should API parameter and return value constraints be formally defined?
  If so, how?

Think of this as defining an API schema.  For example: When creating a VM, which
parameters are required/optional?  What are the valid formats for specifying a
VM disk?  What are all of the possible task states?  Is there a maximum length
for the storage domain description?  

> New API acceptance process
> ==========================
>  - What is the process to suggest new API calls?

New APIs should be proposed on a mailing list.  This allows everyone to
participate in the conversation and preserves the comments.  If the API is
simple, a patch the provides a concrete example of implementation is
recommended.  Once the API design is agreed upon, patches can be submitted via
the standard method (gerrit) to implement a new experimental API based on the
design.  The submitter of the patches should reply to the design discussion
thread to notify participants of the available code.

>  - Who can ack such a change?

API changes should be subject to wider approval than a simple change to an
internal component.  I believe that the +1,-1 system works well here and we
should seek approvals from all participants in the design discussion if

>  - Does someone have veto rights?

Anyone can NACK an API design.  Same rules as for normal code.

>  - Are there experimental APIs?

Yes!  Dave Allan has mentioned that from his experience in libvirt, it would be
very nice to have experimental APIs that can be improved before being baked into
the supportable API.  I definitely agree.  In fact, all new APIs should go
through a period of being experimental.  Experimental API functions should
begin with '_'.  Once deemed stable, the '_' can be removed.

> API deprecation process
> =======================
>  - Do we allow deprecation?

I would like to allow deprecation because it grants us an avenue to clean up the
API from time to time.  That being said, I am not aware of a clean way to do
this without breaking old clients too badly.  At a minimum, an API would need to
be deprecated for at least 2 years before it can be removed.  How will this
decision influence the initial API design?  Are there features that we can build
into an API that can ease the burden of deprecation on API consumers?

>  - When can an API call be deprecated?

As a matter of last resort.  Deprecation must last for an agreed-upon minumum
time period (for supportability) before an API may be removed.

>  - Who can ack such a change?
>  - Does someone have veto rights?
Same as above.

> API change process
> ==================
>  - Can calls be modified or no symbol can ever repeat in a different form

I would suggest libvirt's model here.  APIs can be extended by passing flags to
enable new behavior.  New parameters can be added to an API as long as they are

>  - When can an API call be deprecated?
See above.

>  - Who can ack such a change?
>  - Does someone have veto rights?
Same as above.

> API versioning
> ==============
>  - Is the API versioned as a whole, is it per subsystem (storage, networking,
>    etc..) or is each call versioned by itself.

The API should be versioned as a whole.  This version should be the same as the
software release version.  Additionally, the API should support a list of
capabilities that can be used to express features that can not be expressed by
the presense of a function signature.  For example, the supported storage domain
types.  The ovirt-engine rest API has a decent capabilities API.

>  - What happens when old clients connects to a newer server.

The API is append-only (with two exceptions) so there should never be a problem
with this.

 - Experimental functions may be missing
 - Deprecated functions may have been removed

>  - What happens when a new client connects to an older sever.

This is a bit harder.  We need to handle the following cases:

1) Server wants to use an API call that may not exist on an old version.

An attempt to call a non-existing function should result in a standardized error
that the client can handle appropriately.  In such a case, a client that wants
to support older servers would need to handle the error and perform the needed
operation using an alternate method.  To ease this process for clients, our API
should have a registry of allowed methods.  In REST this would be RSDL.  It
could also be exported as a component of the capabilities API.

2) Server wants to supply unrecognized parameters to a function.

Anytime a new parameter is added to a function, a corresponding flag should be
specified to enable handling of that parameter.  In this way, an old server can
return an error for 'Unknown flag'.

Have a missed any cases?

>  - How will versioning be expressed in the bindings?

The API should have a call to return the overall version.  Also, the
capabilities call should list all noteworthy features that are present.

>  - Do we retrict newer clients from using old APIs when talking with a new
>    server?

No.  A new client that wants to be the most compatible across vdsm versions may
choose to use an old API (even if a flashier one is available).

Adam Litke <a...@us.ibm.com>
IBM Linux Technology Center

vdsm-devel mailing list

Reply via email to