<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:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" 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=us-ascii">
<meta name="Generator" content="Microsoft Word 12 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@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;}
@font-face
{font-family:Verdana;
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;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0in;
margin-right:0in;
margin-bottom:0in;
margin-left:.5in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
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;}
/* List Definitions */
@list l0
{mso-list-id:1573000886;
mso-list-type:hybrid;
mso-list-template-ids:-740635240 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l0:level1
{mso-level-number-format:bullet;
mso-level-text:\F0B7;
mso-level-tab-stop:none;
mso-level-number-position:left;
text-indent:-.25in;
font-family:Symbol;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
--></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">Keystone is using XSD1.1 already.<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>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Mark, I totally agree with you in that we need a “contract” to a service, may it WADL or whatever IDL you use… For us, we have used WADL as a mere contract
(among our services and QA), and that’s about it. We don’t generate code from WADL, nor try to bake code to the WADL. Perhaps, this is an area where things can go off the chart, as you mentioned… But, we need a contract. Particularly, an API contract:<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>
<p class="MsoListParagraph" style="text-indent:-.25in;mso-list:l0 level1 lfo1"><![if !supportLists]><span style="font-size:11.0pt;font-family:Symbol;color:#1F497D"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">
</span></span></span><![endif]><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Should not expose language-specifics… For example, if the contract takes into account the dynamism of Python, that’s wrong, IMHO, because someone
else may (and will) try to implement the contract in Java or C and will find it awkward.<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-.25in;mso-list:l0 level1 lfo1"><![if !supportLists]><span style="font-size:11.0pt;font-family:Symbol;color:#1F497D"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">
</span></span></span><![endif]><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Should allow some level of automated validation; so, I know that I just checked something in that breaks the API. For this reason, I like XSD validation
and Scala <a href="http://code.google.com/p/specs/">Specs</a> for full specs-driven coding.<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-.25in;mso-list:l0 level1 lfo1"><![if !supportLists]><span style="font-size:11.0pt;font-family:Symbol;color:#1F497D"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">
</span></span></span><![endif]><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Most importantly of all, should be “<i>precise, unambiguous, and easy to understand and maintain</i>” like you mentioned, since we are ultimately
consumers of the contract.<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>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">In the past, WADL + XSD have served us well (to the extent that we use them for); but, I am definitely open for any other approach out there that meets the
above use-cases…<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>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Cheers,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Liem<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"><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""> Christopher B Ferris [mailto:chrisfer@us.ibm.com]
<br>
<b>Sent:</b> Friday, June 15, 2012 6:57 AM<br>
<b>To:</b> Mark Nottingham<br>
<b>Cc:</b> Nguyen, Liem Manh; openstack@lists.launchpad.net<br>
<b>Subject:</b> [Openstack] WADL [was: v3 API draft (update and questions to the community)]<o:p></o:p></span></p>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;font-family:"Verdana","sans-serif"">+1 <o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;font-family:"Verdana","sans-serif""><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.0pt;font-family:"Verdana","sans-serif"">Over-reliance on WADL will only make it more challenging to gracefully evolve the APIs such that implementations can be forwards and/or backwards compatible, especially when
exchanging XML based on an XSD that is not carefully crafted with proper extensibility points incorporated throughout the schema design, unless we were to adopt XSD1.1 which has an optional open content model (but which has not yet seen wide adoption, sadly).<br>
<br>
Cheers,<br>
<br>
Christopher Ferris<br>
IBM Distinguished Engineer, CTO Industry and Cloud Standards<br>
Member, IBM Academy of Technology<br>
IBM Software Group, Standards Strategy<br>
email: chrisfer@us.ibm.com<br>
Twitter: christo4ferris<br>
phone: +1 508 234 2986<o:p></o:p></span></p>
</div>
<p class="MsoNormal"><span style="font-size:10.0pt;font-family:"Verdana","sans-serif""><br>
<br>
<span style="color:#990099">-----openstack-bounces+chrisfer=us.ibm.com@lists.launchpad.net wrote: -----</span><o:p></o:p></span></p>
<div>
<div style="border:none;border-left:solid black 1.5pt;padding:0in 0in 0in 4.0pt">
<p class="MsoNormal" style="margin-bottom:12.0pt"><span style="font-size:10.0pt;font-family:"Verdana","sans-serif"">To: "Nguyen, Liem Manh" <liem_m_nguyen@hp.com><br>
From: Mark Nottingham <br>
Sent by: openstack-bounces+chrisfer=us.ibm.com@lists.launchpad.net<br>
Date: 06/14/2012 08:34PM<br>
Cc: "openstack@lists.launchpad.net" <openstack@lists.launchpad.net><br>
Subject: [Openstack] WADL [was: v3 API draft (update and questions to the community)]<o:p></o:p></span></p>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt"><span style="font-family:"Courier New"">Hi Liem,<br>
<br>
I'm one of the folks who helped Marc get WADL off of the ground. At the time, my use cases were exactly as you describe: documentation (e.g., <<a href="https://github.com/mnot/wadl_stylesheets">https://github.com/mnot/wadl_stylesheets</a>>) and testing.<br>
<br>
Even back then, there was a lot of discussion in the community; e.g., see:<br>
<a href="http://bitworking.org/news/193/Do-we-need-WADL">http://bitworking.org/news/193/Do-we-need-WADL</a><br>
<a href="http://old.nabble.com/Is-it-a-good-idea-to-make-your-WADL-available--tc6087155r1.html">
http://old.nabble.com/Is-it-a-good-idea-to-make-your-WADL-available--tc6087155r1.html</a><br>
<a href="http://www.25hoursaday.com/weblog/CommentView.aspx?guid=f88dc5a6-0aff-44ca-ba42-38c651612092">
http://www.25hoursaday.com/weblog/CommentView.aspx?guid=f88dc5a6-0aff-44ca-ba42-38c651612092</a><br>
<br>
I think many of the concerns that were expressed then are still valid -- some even within these limited uses. In no particular order:<br>
<br>
* People can and will use WADL to represent a "contract" to a service (really, an IDL), and "bake" client code to a snapshot of it in time. While it's true that the client and server need to have agreement about what goes on the wire and what it means, the
assumptions around what guarantees WADL makes are not well-thought-out (in a manner similar to WSDL), making clients generated from it very tightly bound to the snapshot of the server they saw at some point in the past. This, in turn, makes evolution / extension
of the API a lot harder than it needs to be.<br>
<br>
* WADL's primitives are XML Schema datatypes. This is a horrible match for dynamic languages like Python.<br>
<br>
* WADL itself embodies certain patterns of use that tend to show through if you design for it; these may or may not be the best patterns for a particular use case. This is because HTTP and URLs are very flexible things, and it isn't expressive enough to cover
all of that space. As a result, you can end up with convoluted APIs that are designed to fit WADL, rather than do the task at hand.<br>
<br>
>From what I've seen, many developers in OpenStack are profoundly uninterested in working with WADL. YMMV, but AFAICT this results in the WADL being done by other folks, and not matching the reality of the implementation; not a good situation for anyone.<br>
<br>
What we need, I think, is a specification of the API that's precise, unambiguous, and easy to understand and maintain. I personally don't think WADL is up to that task (at least as a primary artefact), so (as I mentioned), I'm going to be proposing another
approach.<br>
<br>
Cheers,<br>
<br>
<br>
<br>
On 15/06/2012, at 2:08 AM, Nguyen, Liem Manh wrote:<br>
<br>
> IMHO, a well-documented WADL + XSD would say a thousand words (maybe more)... And can serve as a basis for automated testing as well. I understand that the v3 API draft is perhaps not at that stage yet; but, would like to see a WADL + XSD set as soon as
the concepts are solidified.<br>
> <br>
> Liem<br>
> <br>
> -----Original Message-----<br>
> From: openstack-bounces+liem_m_nguyen=hp.com@lists.launchpad.net [<a href="mailto:openstack-bounces+liem_m_nguyen=hp.com@lists.launchpad.net">mailto:openstack-bounces+liem_m_nguyen=hp.com@lists.launchpad.net</a>] On Behalf Of Mark Nottingham<br>
> Sent: Tuesday, June 12, 2012 8:43 PM<br>
> To: Gabriel Hurley<br>
> Cc: openstack@lists.launchpad.net<br>
> Subject: Re: [Openstack] [keystone] v3 API draft (update and questions to the community)<br>
> <br>
> <br>
> On 13/06/2012, at 1:24 PM, Gabriel Hurley wrote:<br>
> <br>
>> Totally agree with all of Jay's points, and I also couldn't agree more with Mark on the importance of being crystal clear, and not operating on just a "common understanding" which is quickly misunderstood or forgotten.<br>
>> <br>
>> Ideally I'd like to see an OpenStack API feature contract of some sort... essentially a document describing the FULL list of features, how those parameters are controlled and how they would interact, and what a project should do if they do not implement
an API feature (hopefully only for technical reasons such as Keystone paging with LDAP or swift with complex DB-esque operations). This isn't saying we should have a unified API spec, I'm talking solely about a contract for the features all APIs should strive
to support.<br>
>> <br>
>> This would be a big project, but everyone would then have a common agreement about what the user experience of interacting with OpenStack should be. The project APIs as they stand are siloed and stunningly inconsistent, and I'd love to work toward fixing
that.<br>
> <br>
> Absolutely. <br>
> <br>
> One of my other projects is to rewrite the API as a proper specification (in a style similar to an Internet-Draft, not that we'd necessarily publish it as one).<br>
> <br>
> I should have something to show soon; if you're interested in helping out, that'd be great.<br>
> <br>
> Cheers,<br>
> <br>
> <br>
>> My two cents,<br>
>> <br>
>> - Gabriel<br>
>> <br>
>>> -----Original Message-----<br>
>>> From: openstack-bounces+gabriel.hurley=nebula.com@lists.launchpad.net<br>
>>> [<a href="mailto:openstack-">mailto:openstack-</a><br>
>>> bounces+gabriel.hurley=nebula.com@lists.launchpad.net] On Behalf Of<br>
>>> Mark Nottingham<br>
>>> Sent: Tuesday, June 12, 2012 7:20 PM<br>
>>> To: Jay Pipes<br>
>>> Cc: openstack@lists.launchpad.net<br>
>>> Subject: Re: [Openstack] [keystone] v3 API draft (update and questions to<br>
>>> the community)<br>
>>> <br>
>>> <br>
>>> On 13/06/2012, at 3:31 AM, Jay Pipes wrote:<br>
>>> <br>
>>>> This isn't necessarily true. Nova's compute layer goes through a number of<br>
>>> steps to ensure a semi-transactional nature to certain operations like<br>
>>> resizing. Certain times a query needs to indicate that it intends to make a<br>
>>> reservation of resources (see quota/reservation system now .. this is the<br>
>>> SELECT FOR UPDATE paradigm) and other times, the query doesn't care<br>
>>> about such things. In the latter case, there aren't expectations that the list<br>
>>> returned is 100% accurate according to the state of the database at a<br>
>>> particular timestamp of when the transaction occurred. In this case, filters<br>
>>> and optimistic pagination works perfectly fine, IMHO.<br>
>>> <br>
>>> That might work, but we need to be crystal-clear about the semantics of<br>
>>> what we're giving back; having it understood between OpenStack projects<br>
>>> isn't good enough.<br>
>>> <br>
>>> I.e., we're not building the APIs just for Horizon; they're for lots of folks, and<br>
>>> subtle semantics -- even when well-documented, much less when they're<br>
>>> not -- are often misunderstood.<br>
>>> <br>
>>> Cheers,<br>
>>> <br>
>>> --<br>
>>> Mark Nottingham <a href="http://www.mnot.net/">http://www.mnot.net/</a><br>
>>> <br>
>>> <br>
>>> <br>
>>> <br>
>>> _______________________________________________<br>
>>> Mailing list: <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
>>> Post to : openstack@lists.launchpad.net<br>
>>> Unsubscribe : <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
>>> More help : <a href="https://help.launchpad.net/ListHelp">https://help.launchpad.net/ListHelp</a><br>
>> <br>
>> <br>
>> <br>
>> _______________________________________________<br>
>> Mailing list: <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
>> Post to : openstack@lists.launchpad.net<br>
>> Unsubscribe : <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
>> More help : <a href="https://help.launchpad.net/ListHelp">https://help.launchpad.net/ListHelp</a><br>
> <br>
> --<br>
> Mark Nottingham <a href="http://www.mnot.net/">http://www.mnot.net/</a><br>
> <br>
> <br>
> <br>
> <br>
> _______________________________________________<br>
> Mailing list: <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
> Post to : openstack@lists.launchpad.net<br>
> Unsubscribe : <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
> More help : <a href="https://help.launchpad.net/ListHelp">https://help.launchpad.net/ListHelp</a><br>
<br>
--<br>
Mark Nottingham <a href="http://www.mnot.net/">http://www.mnot.net/</a><br>
<br>
<br>
<br>
<br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
Post to : openstack@lists.launchpad.net<br>
Unsubscribe : <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a><br>
More help : <a href="https://help.launchpad.net/ListHelp">https://help.launchpad.net/ListHelp</a></span><span style="font-size:10.0pt;font-family:"Verdana","sans-serif""><o:p></o:p></span></p>
</div>
</div>
</div>
</div>
</body>
</html>