Open Stack

On 09/30/2015 04:08 AM, Dougal Matthews wrote:
> Hi,
>
> What is the standard practice for defining public API's for OpenStack
> libraries? As I am working on refactoring and updating tripleo-common I have
> to grep through the projects I know that use it to make sure I don't break
> anything.

The API working group exists, but they focus on REST APIs so they don't 
have any guidelines on library APIs.

> Personally I would choose to have a policy of "If it is documented, it is
> public" because that is very clear and it still allows us to do internal
> refactoring.
>
> Otherwise we could use __all__ to define what is public in each file, or
> assume everything that doesn't start with an underscore is public.

I think assuming that anything without a leading underscore is public 
might be too broad. For example, that would make all of libutils 
ostensibly a "stable" interface. I don't think that's what we want, 
especially this early in the lifecycle.

In heatclient, we present "heatclient.client" and "heatclient.exc" 
modules as the main public API, and put versioned implementations in 
modules.

heatclient
|- client
|- exc
\- v1
   |- client
   |- resources
   |- events
   |- services

I think versioning the public API is the way to go, since it will make 
it easier to maintain backwards compatibility while new needs/uses evolve.

-- 
Ryan Brown / Senior Software Engineer, Openstack / Red Hat, Inc.