<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Jul 7, 2014 at 2:51 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">
<div class="">On Mon, Jul 7, 2014 at 2:43 PM, Steve Martinelli <span dir="ltr"><<a href="mailto:stevemar@ca.ibm.com" target="_blank">stevemar@ca.ibm.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><font size="3" face="sans-serif">>>1) We already have identity-api,
which will need to be updated once the spec is completed anyway.</font>
<br>
<br><font size="3">>So my thinking is to merge the content of openstack/identity-api
into openstack/keystone-specs. We use identity-api just like we use keystone-specs
anyway, but only for a subset of >our work.</font>
<br><font size="3"> </font>
<br></div><font size="3">I think that would solve a lot of the issues I'm having
with the current spec-process. I really don't want to have the same content
being managed in two different places (even though the specs content probably
won't be managed). Chalk it up to another discussion at the hackathon.</font>
<br></blockquote><div><br></div></div><div>I like this idea too. Ideally we'd convince the rest of the projects to treat theirs the same way. It seems like the replication of info is what you want to avoid.</div></div>
</div></div></blockquote><div><br></div><div>Replication leads to inconsistency, and that's exactly what I'd like to avoid.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br>
</div><div>We also have end-users relying on this information for creating and working on client tools and SDKs, though. I don't really want to publish end-user documentation out of -specs repos. So do you think there is sufficient information in the api-site repo for Identity API v3 for end users?</div>
</div></div></div></blockquote><div><br></div><div>Why not? AFAICT, they're referring directly to openstack/identity-api for the most part, because (and I assume you're referring to [1] when you say "api-site") it's currently regarded as the source of truth for the API. Although the API site is prettier, openstack/identity-api provides human-readable documentation on the API, making the API site redundant, unmaintained, and therefore inconsistent and out of date. The Identity v3 slice of the API site causes more pain than anything else for me, so my perspective is probably biased here.</div>
<div><br></div><div>[1] <a href="http://developer.openstack.org/api-ref-identity-v3.html">http://developer.openstack.org/api-ref-identity-v3.html</a><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">
<div><br></div><div>Thanks,</div><div>Anne</div><div><div class="h5"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<font face="sans-serif"><br>
</font>
<br><font size="1" face="Arial">Regards,</font>
<br>
<br><font size="3" color="#8f8f8f" face="Arial"><b>Steve Martinelli</b></font><font size="1" face="Arial"><br>
Software Developer - Openstack<br>
Keystone Core Member</font>
<table width="680" style="border-collapse:collapse">
<tbody><tr height="8">
<td width="680" colspan="2" style="border:0px solid rgb(0,0,0);padding:0px">
<hr>
</td></tr><tr valign="top" height="8">
<td width="420" style="border:0px solid rgb(0,0,0);padding:0px"><font size="1" color="#4181c0" face="Arial"><b>Phone:</b></font><font size="1" color="#5f5f5f" face="Arial">
<a href="tel:1-905-413-2851" value="+19054132851" target="_blank">1-905-413-2851</a></font><font size="1" color="#4181c0" face="Arial"><b><br>
E-mail:</b></font><font size="1" color="#5f5f5f" face="Arial"> </font><a href="mailto:stevemar@ca.ibm.com" target="_blank"><font size="1" color="#5f5f5f" face="Arial"><u>stevemar@ca.ibm.com</u></font></a>
</td><td width="259" style="border:0px solid rgb(0,0,0);padding:0px">
<div align="right"><font size="1" color="#5f5f5f" face="Arial">8200 Warden Ave<br>
Markham, ON L6G 1C7<br>
Canada</font></div></td></tr></tbody></table>
<br>
<br>
<br>
<br>
<br><font size="1" color="#5f5f5f" face="sans-serif">From:
</font><font size="1" face="sans-serif">Dolph Mathews <<a href="mailto:dolph.mathews@gmail.com" target="_blank">dolph.mathews@gmail.com</a>></font>
<br><font size="1" color="#5f5f5f" face="sans-serif">To:
</font><font size="1" face="sans-serif">"OpenStack Development
Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org" target="_blank">openstack-dev@lists.openstack.org</a>>,
</font>
<br><font size="1" color="#5f5f5f" face="sans-serif">Date:
</font><font size="1" face="sans-serif">07/07/2014 01:39 PM</font>
<br><font size="1" color="#5f5f5f" face="sans-serif">Subject:
</font><font size="1" face="sans-serif">Re: [openstack-dev]
[keystone][specs] listing the entire API in a new
spec</font>
<br>
<hr noshade>
<br>
<br>
<br>
<br><font size="3">On Fri, Jul 4, 2014 at 12:31 AM, Steve Martinelli <</font><a href="mailto:stevemar@ca.ibm.com" target="_blank"><font size="3" color="blue"><u>stevemar@ca.ibm.com</u></font></a><font size="3">>
wrote:</font>
<br><font size="3" face="sans-serif">To add to the growing pains of keystone-specs,
one thing I've noticed is, there is inconsistency in the 'REST API Impact'
section.</font><font size="3"> <br>
</font><font size="3" face="sans-serif"><br>
To be clear here, I don't mean we shouldn't include what new APIs will
be created, I think that is essential. But rather, remove the need to specifically
spell out the request and response blocks.</font><font size="3"> <br>
</font><font size="3" face="sans-serif"><br>
Personally, I find it redundant for a few reasons:</font>
<br>
<br><font size="3">Agree, we need to eliminate the redundancy...</font>
<br><font size="3"> </font>
<br><font size="3"><br>
</font><font size="3" face="sans-serif"><br>
1) We already have identity-api, which will need to be updated once the
spec is completed anyway.</font>
<br>
<br><font size="3">So my thinking is to merge the content of openstack/identity-api
into openstack/keystone-specs. We use identity-api just like we use keystone-specs
anyway, but only for a subset of our work.</font>
<br><font size="3"> </font>
<br><font size="3" face="sans-serif"><br>
2) It's easy to get bogged down in the spec review as it is, I don't want
to have to point out mistakes in the request/response blocks too (as I'll
need to do that when reviewing the identity-api patch anyway).</font>
<br>
<br><font size="3">I personally see value in having them proposed as one
patchset - it's all design work, so I think it should be approved as a
cohesive piece of design.</font>
<br><font size="3"> </font>
<br><font size="3" face="sans-serif"><br>
3) Come time to propose the identity-api patch, there might be differences
in what was proposed in the spec.</font>
<br>
<br><font size="3">There *shouldn't* be though... unless you're just talking
about typos/etc. It's possible to design an unimplementable or unusable
API though, and that can be discovered (at latest) by attempting an implementation...
at that point, I think it's fair to go back and revise the spec/API with
the solution.</font>
<br><font size="3"> </font>
<br><font size="3"><br>
</font><font size="3" face="sans-serif"><br>
Personally I'd be OK with just stating the HTTP method and the endpoint.
Thoughts?</font>
<br>
<br><font size="3">Not all API-impacting changes introduce new endpoint/method
combinations, they may just add a new attribute to an existing resource
- and this is still a bit redundant with the identity-api repo.</font>
<br>
<br><font size="3"><br>
</font><font size="3" face="sans-serif"><br>
Many apologies in advance for my pedantic-ness!</font>
<br>
<br><font size="3">Laziness*</font>
<br>
<br><font size="3">(lazy engineers are just more efficient)</font>
<br>
<br><font size="1" face="Arial"><br>
Regards,</font><font size="3"> <br>
</font><font size="3" color="#8f8f8f" face="Arial"><b><br>
Steve Martinelli</b></font><font size="1" face="Arial"><br>
Software Developer - Openstack<br>
Keystone Core Member</font><font size="3"> </font>
<table width="680" style="border-collapse:collapse">
<tbody><tr height="8">
<td width="678" colspan="2" style="border:0px solid rgb(0,0,0);padding:1px">
<hr>
</td></tr><tr valign="top" height="8">
<td width="418" style="border:0px solid rgb(0,0,0);padding:1px"><font size="1" color="#4181c0" face="Arial"><b>Phone:</b></font><font size="1" color="#5f5f5f" face="Arial">
</font><a href="tel:1-905-413-2851" target="_blank"><font size="1" color="blue" face="Arial"><u>1-905-413-2851</u></font></a><font size="1" color="#4181c0" face="Arial"><b><br>
E-mail:</b></font><font size="1" color="#5f5f5f" face="Arial"> </font><a href="mailto:stevemar@ca.ibm.com" target="_blank"><font size="1" color="#5f5f5f" face="Arial"><u>stevemar@ca.ibm.com</u></font></a><font size="3">
</font>
</td><td width="257" style="border:0px solid rgb(0,0,0);padding:1px">
<div align="right"><font size="1" color="#5f5f5f" face="Arial">8200 Warden Ave<br>
Markham, ON L6G 1C7<br>
Canada</font></div></td></tr></tbody></table>
<br><font size="3"><br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list</font><font size="3" color="blue"><u><br>
</u></font><a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank"><font size="3" color="blue"><u>OpenStack-dev@lists.openstack.org</u></font></a><font size="3" color="blue"><u><br>
</u></font><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank"><font size="3" color="blue"><u>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</u></font></a><font size="3"><br>
</font>
<br><tt><font>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
</font></tt><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank"><tt><font>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</font></tt></a><tt><font><br>
</font></tt>
<br>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div></div></div><br></div></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>