REST API docs

[Patrick Williams]

On Tue, Aug 01, 2017 at 03:07:36PM +1000, Stewart Smith wrote:
> The documentation up at:
> https://github.com/openbmc/docs/blob/master/host-management.md
> says /org/openbmc but we here tales in internal bug reports that
> everything is switching to /xyz/openbmc_project.
> 
> Except, I don't recall seeing any deprecation plan.... is there
> one?
> 
> We're heavily using this now for op-test-framework, and there's a patch
> to switch it, but I need to know how far back/forwards the existing/new
> interfaces are supported.
> 
> See:
> https://github.com/open-power/op-test-framework/pull/150/commits/e05b1a89e032b1bbe14d9a177afa46f1a2c6413c
> 
> Also, could some more effort please be put into communicating these
> changes. These kind of surprises aren't great for our already
> constrained team.

Stewart,

I don't know why this is a surprise.  We have been communicating in
various avenues that the /org/openbmc APIs defined for Barreleye
were all deprecated the day we split the 2.0 development branch.
I alluded to this even in the email announcing the v1.0 tag:
    https://lists.ozlabs.org/pipermail/openbmc/2016-June/003707.html

It is a violation of the dbus spec for us to be using /org/openbmc since
it is not a domain name we have control over.

None of the /org/openbmc interfaces went through any proper interface
design.  They were all defined and implemented ad-hoc by individual
developers as part of the Barreleye proof-of-concept work.  There are
numerous inconsistencies in their original form.

One of the first pieces of work we defined and began working on was a
dbus interface YAML specification, from which we generate compile-time
enforced dbus bindings to ensure compatibility between applications.
All of the xyz.openbmc_project interfaces have formal documentation in
the phosphor-dbus-interfaces repository, which had its first commits in
October of last year.

The dbus interfaces you are _moving to_ were defined and implemented
in December of last year and we moved over to them as a whole within
the code base by Feb.  Your first commit "Initial OpenBMC support" in
your repository wasn't until late Feb, so you were already using the
wrong interfaces.

We have been working very closely with the automated test group that
works on the openbmc-test-automation repository.  I was pretty certain
that within IBM there is some affinity between the team working on this
repository and the team working on your repository, isn't there?  In
fact, I clearly recall discussions within IBM questioning why the
op-test-framework would not be building on top of the existing Robot
support provided by openbmc-test-automation rather than implement
a different custom framework.

I was not aware that you had written your own test automation suite that
was using REST APIs and you were not relying on the existing and
supported openbmc-test-automation repository.  I also did not hear any
inquiry from you, either publicly or privately, on which APIs you should
be targeting for work you were doing.

The deprecation plan is, and has for the entire 2.0 development branch,
that 1.0 and 2.0 have a complete API break and there is no attempt at
backwards compatibility.  A clear requirement of a 2.0 tag is that all
/org/openbmc interfaces have been removed and replaced by something
documented in phosphor-dbus-interfaces and implemented within the code
base.  We have been doing that at a fairly regular pace the entire
year.

-- 
Patrick Williams
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Digital signature
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20170801/6cd365f0/attachment.sig>