Sometimes when I'm discussing or reviewing proposed specs, I feel as though I may have incorrect assumptions about what the Neutron API is _for_. And certainly I feel that we lack good unified documentation of it - or at least, that I haven't yet found that documentation, if it exists. So I'd like to start a conversation about that here.
_What is important: the API, or documented use cases?_ Being theoretically inclined, I tend to assume that if an API exists, it is the primary thing, and hence that everything that is expressible in that API should make sense and be implemented by at least some implementations. (It's fine for the API to explicit exclude certain combinations of properties or calls; those exclusions then become part of the definition of 'the API'. It's also fine for particular implementations only to implement a subset of the API.) But a perfectly consistent alternative position would be to say that that is _not_ the case with the Neutron API, and - rather - what really matters is our set of documented use cases [1]. If that was the view, then the API would simply be a piece of how we provide those use cases, and anything _else_ that the resulting API happened to be able to express would be regarded technically as an accident or 'unspecified behavior'. [1] http://docs.openstack.org/networking-guide/deploy.html Which of those positions do we actually take? (What is the overall contract that Neutron provides to the rest of the OpenStack world?) If it's the latter, then much of the rest of this email may be moot. But I'll write it anyway in case it's the former - i.e. that we believe the Neutron API is important as a more general thing than just the documented use cases - or in case it's interesting for other reasons. _What should be expressed on the Neutron API?_ My first intuition is that the Neutron API should _only_ describe the connectivity and networking services that it provides to instances - L2, L3, security, service chains, DNS, DHCP etc. etc. - and primarily this is indeed what it does. But it only takes a slightly longer look to see other things that are not part of specifying the connectivity or services that can be observed by instances, but instead directions to the (assumed) implementation about how that connectivity should be implemented. For example, the 'provider' API extension is entirely in the latter camp. So in practice it seems we use the Neutron API for two purposes: 1. To describe the connectivity and networking services that Neutron provides to instances. 2. As a convenient central distribution point for instructions to assumed networking implementations. Is that right, as a description of current reality? Is it right, in terms of what we _should_ be doing? Should we, for example, perhaps have a clearer formal separation between (1) and (2)? _Documentation_ Whatever is the consensus on the questions raised here, I'd like that to be explicitly recorded somewhere, and volunteer to do that. Not sure yet whether that should be in the Neutron devref, or in the networking guide - opinions welcome! Also, if we agree that the Neutron API is a primary thing, I think we should have some unified documentation of it that explains what all the data model objects mean. I'm not sure I can do all of that myself, but I'd be happy to make a start - so again, opinions welcome on where and how to do that. Apologies if either of these things already exists - in that case please just point to them. Thanks for reading! Please let me know what you think. Neil __________________________________________________________________________ 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
