Open Stack

On Tue, Jan 18, 2022 at 10:49 AM Jeremy Stanley <fungi at yuggoth.org> wrote:
>
> On 2022-01-18 23:21:21 +0500 (+0500), Mahnoor Asghar wrote:
> [...]
> > I am an Outreachy intern, working with OpenStack Ironic on improving
> > their API reference documentation mechanism.
> [...]
>
> Welcome!
>
> > The wider OpenStack community may be facing similar problems
> > maintaining their documentation, and it would be helpful to
> > understand their perspective and concerns - with respect to using
> > such an extension, their expectations from it, collaborating on
> > it, and whether they have additional ideas about how we may bring
> > API documentation closer to the code.
> [...]
>
> Keep in mind that developers of OpenStack's services have
> traditionally held the belief that a good public API should be
> versioned independently from the software which implements it. One
> version of the software may provide multiple API versions, and
> there's not necessarily a 1:1 correlation between public REST API
> methods and the internal Python API methods which implement them. I
> suspect this has driven some of the desire to separate REST API
> documentation from the source code itself.

And the API version contracts we've tended to offer has been a very
linear progression matching the software versions, for the most part.
I think as the groups of maintainers have evolved, I believe the
traditional belief may no longer really hold true. Or at least, there
doesn't seem to be a good reason to continue to keep aspects
disjointed and separated, at least that I'm aware of. I guess to put
it another way, we have finite capacity/bandwidth, and anything we do
to reduce hurdles, can help us further our work.

>
> There have been past attempts to implement self-describing APIs,
> scraping running services in CI jobs, and so on. I don't recall the
> details, but folks who were active in the API SIG likely have a
> clearer recollection and can probably relate some of the challenges
> encountered with various approaches.
> --
> Jeremy Stanley