On the state of documentation

[Tanous, Ed]

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.

We are already seeing the result of this in a number of APIs that target very specific and unsustainable APIs.  A great example is the URL for the BMC Ethernet device that's currently hardcoded in the webui.
/xyz/openbmc_project/inventory/system/chassis/motherboard/boxelder/bmc/Ethernet

This URL has several assumptions baked into it that make it a non-starter for targeting interfaces on new implementations.

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'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?

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.

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.

Thanks,

-Ed

> -----Original Message-----
> From: openbmc [mailto:openbmc-
> bounces+ed.tanous=intel.com at lists.ozlabs.org] On Behalf Of Patrick
> Williams
> Sent: Wednesday, November 15, 2017 6:41 AM
> To: Stewart Smith <stewart at linux.vnet.ibm.com>
> Cc: OpenBMC Maillist <openbmc at lists.ozlabs.org>
> Subject: Re: On the state of documentation
> 
> The sdbusplus generator that is used on the *-dbus-interfaces repos already
> supports generating markdown documentation for the APIs. This was
> suppose to be roughly equivalent to the “old” documentation.
> 
> The plan was:
>   1. Enhance the make files to run the markdown generator.
>   2. Add a Jenkins job that would run it and publish to the openbmc.github.io
> repo on merge to an *-dbus-interfaces repo.
> 
> I don’t think either of these steps has been done but they are also not a
> significant effort.
> 
> Have you looked at the current markdown generation output to see if this
> would be helpful?
> 
> Patrick
> Sent from my iPhone
> 
> > On Nov 15, 2017, at 12:11 AM, Stewart Smith
> <stewart at linux.vnet.ibm.com> wrote:
> >
> > Hi all,
> >
> > thought I'd try and contribute my thoughts here, as a consumer of
> > OpenBMC rather than a developer on it.
> >
> > The message has long been that the REST API is what should be used to
> > interact with the BMC, and as such we now have a lot of tooling that
> > does just that (and we're not the only ones).
> >
> > Over the past $months, it's been frustrating (to say the least) that
> > there hasn't been any good documentation of this API.
> >
> > Indeed, If I look at the API on the "Rusty's API Scale" of usability:
> > http://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html
> > http://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html
> > It's all pretty high on the negatives, although it does vary on what
> > specific API you're looking at.
> >
> > A lot of the negative scoring here is due to a near complete absence
> > of documentation. Most things that we use have ended up being
> > documented either in the implementation (which may or may not allow
> > you to use it correctly), or by some random thread on an IBM internal slack
> channel.
> >
> > Additionally, this issue and PR has come up:
> > "Remove org.openbmc.* from REST server"
> > https://github.com/openbmc/openbmc/issues/2378
> > https://gerrit.openbmc-project.xyz/#/c/7422/
> >
> > This morning, I took a stab at going through the documentation and
> > working out what this means for current documentation:
> > https://gerrit.openbmc-project.xyz/#/c/7916/
> >
> > In short: it's not good. There is now no longer documentation even
> > describing how to turn the host on and off.
> >
> > If the above "remove org.openbmc.* from REST server" is merged, there
> > will be *ZERO* documentation on how to turn the host on and off -
> > which is about the most simple thing you want to do with a BMC.
> >
> > Is there a plan to attack this?
> >
> > IMNSHO I'd like to see a standard interface be "the way" to talk to
> > OpenBMC based systems, something like RedFish, which I noticed there
> > was the start of some work on here:
> > https://gerrit.openbmc-project.xyz/#/c/7786/
> >
> > But even if RedFish/IPMI became *the* way externally, the internal
> > APIs (as in, d-bus APIs) could probably also do with some love.
> >
> > My initial stab at helping with that is:
> > https://gerrit.openbmc-project.xyz/#/c/7923/
> > but even then, that very same API raises a lot of other questions that
> > I haven't addressed - and even in that pull request, I've made a bunch
> > of sweeping statements binding the OpenBMC developers to certain API
> > stability constraints.
> > --
> > Stewart Smith
> > OPAL Architect, IBM.
> >
>