Open Stack

Hi,

During the review of https://review.openstack.org/#/c/240815, I started
to think about how there are some very specific changes to the Neutron
API that are getting flagged with DocImpact, and contributors are
attempting to add them to the Networking Guide.

Specifically, 240815 attempts to add information about cases where a
user supplied MAC address fails validation at the Neutron API layer, and
an error is returned.

The specific MAC addresses that are being rejected are a little in the
weeds, technically. The MAC addresses 00:00:00:00:00:00 and
FF:FF:FF:FF:FF:FF are special addresses (look up RFC7042 if you are a
masochist for more information). It is not normal to assign those MAC
addresses, so Neutron does not allow you to.

Suffice to say, this is a fairly technical bit of literature, and may
not really belong in the Networking Guide.

Ideally, it would be part of some sort of  API documentation, however I
am a little fuzzy on what the status of the API reference is today.

There is http://developer.openstack.org/api-ref-networking-v2.html -
although is that maintained? I've noticed a lot of gaps in it when
consulting it from time to time.

I know for a while there was an import done into the neutron-specs repo,
but it hasn't really ever been touched since the first import, and the
RST conversion was not really complete, a lot of the tables did not
survive the RST conversion experience.

https://github.com/openstack/neutron-specs/commit/eebdf8b039713e58b60b3d9b4bbb5fae5bb5645b

More recently, those files were shuffled into a different part of the
repo

https://github.com/openstack/neutron-specs/commit/415f1eaf5b94fe623ccf7c53dbc26ef3fc798e34

However that's the most that has been done - just moved around. I don't
think there has been any change to the content.

So - where does detailed API documentation live?

Anyway, please forgive the ignorance, I'm sure this has probably been
discussed elsewhere and I'm just not aware.

-- 
Sean M. Collins