On the state of documentation

[Stewart Smith]

"Tanous, Ed" <ed.tanous at intel.com> writes:
> I believe that the lack of good documentation is a symptom of a larger
> issue:  OpenBMC is not targeting a public specification with its REST
> interface.  This has led to certain engineering flexibilities with the
> interface that, while useful for short term to "get something that
> works", make it very difficult to target openbmc an evolving platform.
> In the current model, DBus specifications are pushed directly to the
> end user, which means (nearly) every DBus spec change results in a
> change to end user interfaces.  I don't believe this is sustainable in
> the long run, given the number of platforms that this is targeting and
> the need for reproducible APIs between systems.

I very much agree.

As someone consuming it, for the purposes of automating testing host
firmware (for the purpose of being a host firmware maintainer), it's
been *extroadinarily* frustrating. Upgrading a BMC usually meant 0.5-1
day of working out what API change broke and how to code something that
was safe for more than one OpenBMC build.

Additionally, much of the docs of the DBUS API are currently written
targetting somebody working on OpenBMC internals.

> I would argue that middle to long term we should transition away from
> these interfaces for end-user facing functionality, and move toward
> something that has a standard behind it.  I think the obvious choice
> in this problem space is redfish, but I'm open to other options.

I am 100% with you on that.

RedFish may not be ideal (neither is IPMI), but it's *standard*, so at
least it's not just a OpenBMC problem.

I see at least 2 other BMCs I have to deal with going the RedFish route,
so I'd honestly like to see OpenBMC go there.

I view all the code I've written against the OpenBMC REST API to be
throw-away code... but that's what I've been told by the IBM team they
support, so there hasn't really been a choice apart from rewriting half
of it every month for no discernable good reason.

> I'd like to pose the question:
> Should we move toward deprecating the /xyz and /org style rest
> interfaces, and agree that we should start transitioning to something
> (redfish or not) with a fixed specification?

My vote is YES, *PLEASE* YES.

> Some important key points that I think should be driven by the new model:
> 1. Rest interfaces should not be driven by the underlying DBus interfaces, nor the backend implementation language.
> 2. Interfaces should not contain any "backdoor" type APIs that allow white box style access to internal APIs.  Anything breaking the black box model should be done in a machine specific layer or configuration.
> 3. APIs should give the minimum required amount of information to fulfill the end user use case.
> 4. Interfaces should be backed by the system level security policy (PAM users in the current model).
> 5. Where possible, the implementations should follow an existing specification.  In the cases where the requirements are not supported, the api should follow the style of the supporting interface  (Think redfish OEM command support)
> 6. Documentation changes should be pushed ahead of or along with
> implementation support, with the goal of keeping the documentation
> constantly up to date.

Completely agree.
> Shameless plug: As the person that pushed the aforementioned gerrit
> review for a new thinking on the webserver and redfish, I would love
> comments on architecture decisions and implementation details.

I nearly commented MERGE NOW without even looking, but that's possibly a
bit keen :)

I reckon the Minimum Viable Product for something is enough to do what
TripleO needs (which is probably the same set of things that I need for
OPAL testing). Once it's there, I say go for it - internals can be
cleaned up, but at least those of us consuming OpenBMC have a good way
forward along with an upstream spec to point to and look at.

-- 
Stewart Smith
OPAL Architect, IBM.