<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 12 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">In line (at the bottom)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="margin-left:.5in"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Devananda van der Veen [mailto:devananda.vdv@gmail.com]
<br>
<b>Sent:</b> Friday, June 19, 2015 12:40<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Subject:</b> Re: [openstack-dev] [api][nova][ironic] Microversion API HTTP header<o:p></o:p></span></p>
</div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
<o:p> </o:p></p>
<div>
<div>
<p class="MsoNormal" style="margin-left:.5in">On Wed, Jun 17, 2015 at 7:31 AM Jay Pipes <<a href="mailto:jaypipes@gmail.com">jaypipes@gmail.com</a>> wrote:<o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<p class="MsoNormal" style="margin-left:.5in">On 06/17/2015 06:30 AM, Lucas Alvares Gomes wrote:<br>
>> overlap there rather than competition), how crazy does it sound if we say<br>
>> that for OpenStack Nova is the compute API and Ironic the Bare Metal API and<br>
>> so on? Would that be an unacceptable power grab?<br>
><br>
> It's not that it's unacceptable, but I think that things weren't<br>
> projected that way. Jay started this thread with this sentence:<br>
><br>
> "To be blunt, Nova is the *implementation* of the OpenStack Compute<br>
> API. Ironic is the *implementation* of the OpenStack BareMetal API."<br>
><br>
> Which I don't think is totally correct, at least for Ironic. The<br>
> Ironic's API have evolved and shaped as we implemented Ironic, I think<br>
> that some decisions we made in the API makes it clear, e.g:<br>
><br>
> * Resources have JSON attributes. If you look at some attributes of<br>
> the resources you will see that they are just a JSON blob. That's by<br>
> design because we didn't know exactly how the API should look like and<br>
> so by having these JSON fields it allows us to easily extend the<br>
> resource without changing it's structure [1] (see driver_info,<br>
> instance_info, extra)<br>
<br>
OK. Nothing wrong with that.<br>
<br>
> * We have a vendor endpoint. This endpoint allows vendor to extend our<br>
> API to expose new hardware capabilities that aren't present in the<br>
> core API. Once multiple vendors starts implementing the same feature<br>
> on this endpoint we then decide whether to promote it to the core API.<br>
<br>
This is a problem. The above means that there is no single OpenStack<br>
BareMetal API. This means developers that want to write against an<br>
OpenStack BareMetal API cannot rely on different deployments of Ironic<br>
exposing the same API. That is a recipe for a lack of interoperability<br>
and decreased developer ease of use.<o:p></o:p></p>
</blockquote>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Nope - not a problem. Actually it's been really helpful. We've found this to be a better way to implement driver extensions -- it's clearly *not* part of Ironic's API, and it's communicated as such in the API itself.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Any standard part of Ironic's functionality is exposed in the standard API, and hardware-specific extensions, which are not supported by enough vendors to be standardized yet, are only exposed through the vendor-specific
API endpoint. It's very clear in the REST API what this is -- the end points are, for example,<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"> GET /v1/nodes/NNNN/vendor_passthru/methods<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"> POST /v1/nodes/NNNN/vendor_passthru?method=foo¶m=bar<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"> GET /v1/drivers/DDDD/methods<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">... and so on. This provides a mechanism to discover what resources and methods said hardware vendor exposes in their hardware driver. We have always supported out of tree drivers, and it is possible to upgrade
Ironic without upgrading the driver (or vice versa).<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Also to note, our client library doesn't support any of the vendor-specific methods, and never will. It only supports Ironic's API's ability to *discover* what vendor-specific methods that driver exposes, and then
to transparently call to them. And none of that is relevant to other OpenStack projects.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">So if an operator wants to write a custom app that uses foo-vendor's advanced-foo-making capabilities because they only buy Foo hardware -- that's great. They can do that. Presumably, they have a support contract
with Foo vendor. Ironic is merely providing the transport between them.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"> <o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<p class="MsoNormal" style="margin-left:.5in"><br>
> * There's a "reservation" attribute in the Node's resource [1] which<br>
> valueis the hostname of the conductor that is currently holding an<br>
> exclusive lock to act upon this node. This is because internally we<br>
> use a distributed hashing algorithm to be able to route the requests<br>
> from the API service to a conductor service that is able to manage<br>
> that Node. And having this field in the API<br>
<br>
That is just leaking implementation inappropriately out of the public<br>
REST API, and shouldn't be encouraged, IMHO. Nova has a number of these<br>
leaky parts of its API, too, of course. Just look at the os-guests API<br>
extension, which only works when you're using Xen under the hood,<br>
thereby leaking implementation details about the underlying<br>
infrastructure out through the public REST API.<o:p></o:p></p>
</blockquote>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">yes, this is leaky in the purest sense, but remember that ironic doesn't expose a *public* API. Only operators and other services should be talking directly to it -- and this field was requested by operators who
find it helpful to know which service has locked a resource.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<p class="MsoNormal" style="margin-left:.5in"><br>
> I don't think that any of those decisions were bad by the way, this<br>
> have helped us a lot to understand how a service to manage Bare Metal<br>
> machines should looks like, and we have made wrong decisions too (You<br>
> can get the same information by GET'ing different endpoints in the<br>
> API, the Chassis resources currently have no usage apart from<br>
> logically grouping nodes, etc...)<br>
<br>
Sure, all APIs have warts :) But the warts aren't an excuse to delay<br>
plugging up those leaks. <o:p></o:p></p>
</blockquote>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
<br>
> So back to the topic. if we are removing the project name from the<br>
> Header to facilitate another project to implement the these type of<br>
> APIs I don't think it will help much. Perhaps the API-WG group should<br>
> make say that for new API's the microversion Header should not have<br>
> the projects name in it. Because then, I think we can think about an<br>
> API definition that is decouple from the implementation.<br>
<br>
Sure.<o:p></o:p></p>
</blockquote>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Unless the API-WG is going to actually define the API for every project (or the TC wants to do that), I don't think we can remove the project name from the header.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">If another *project team* wanted to implement a Baremetal Service, and they were required to use the "OpenStack-Baremetal-API-Version" -- or the "OpenStack-API-Version" -- headers, and assuming they don't want to
be sitting second fiddle to the incumbent project's API changes (I mean, if they wanted that, why go make a new project?) it would be difficult for any user to tell the two apart. Imagine a new service returning a lower version number for the same version
header, but the REST API behaves completely differently from any API that Ironic has ever had.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">In other words, requiring projects to use the service name in the API header is going to put OpenStack back in the place of not allowing any competition between projects to provide similar functionality.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><b><i><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">[Rockyg] +1000 I’ve been wondering how humans would be able to tell the various codebases in operation apart if the header is simply “OpenStack” or “OpenStack-Service”
but thought I must be missing something. At least with service, you can tell the *type* of API set and guess the project. Until we get competing projects or services. Hmmm, messaging? With simply “OpenStack, humans and/or computers would have to devine
the service and project. Not something you’d want to do on the fly when you have a million users down and the first clue of why is an “Openstack-API-2.1.36” and an error message. Not error recovery friendly. Please think about how these things play out
in the *not* happy path before making decisions that are hard to change.<o:p></o:p></span></i></b></p>
<p class="MsoNormal"><b><i><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><flame off><o:p></o:p></span></i></b></p>
<p class="MsoNormal"><b><i><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></i></b></p>
<p class="MsoNormal"><b><i><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">--Rocky<o:p></o:p></span></i></b></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">-Deva<o:p></o:p></p>
</div>
</div>
</div>
</div>
</body>
</html>