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.
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
