Open Stack

On Mon, Jul 7, 2014 at 2:51 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> On Mon, Jul 7, 2014 at 2:43 PM, Steve Martinelli <stevemar at ca.ibm.com>
> wrote:
>
>> >>1) We already have identity-api, which will need to be updated once the
>> spec is completed anyway.
>>
>> >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.
>>
>> 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.
>>
>
> 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.
>

Replication leads to inconsistency, and that's exactly what I'd like to
avoid.


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

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.

[1] http://developer.openstack.org/api-ref-identity-v3.html


> Thanks,
> Anne
>
>
>>
>>
>> Regards,
>>
>> *Steve Martinelli*
>> Software Developer - Openstack
>> Keystone Core Member
>> ------------------------------
>>  *Phone:* 1-905-413-2851
>> * E-mail:* *stevemar at ca.ibm.com* <stevemar at ca.ibm.com>
>> 8200 Warden Ave
>> Markham, ON L6G 1C7
>> Canada
>>
>>
>>
>>
>>
>> From:        Dolph Mathews <dolph.mathews at gmail.com>
>> To:        "OpenStack Development Mailing List (not for usage
>> questions)" <openstack-dev at lists.openstack.org>,
>> Date:        07/07/2014 01:39 PM
>> Subject:        Re: [openstack-dev] [keystone][specs] listing the entire
>> API in a        new spec
>> ------------------------------
>>
>>
>>
>>
>> On Fri, Jul 4, 2014 at 12:31 AM, Steve Martinelli <*stevemar at ca.ibm.com*
>> <stevemar at ca.ibm.com>> wrote:
>> To add to the growing pains of keystone-specs, one thing I've noticed is,
>> there is inconsistency in the 'REST API Impact' section.
>>
>> 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.
>>
>> Personally, I find it redundant for a few reasons:
>>
>> Agree, we need to eliminate the redundancy...
>>
>>
>>
>> 1) We already have identity-api, which will need to be updated once the
>> spec is completed anyway.
>>
>> 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.
>>
>>
>> 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).
>>
>> 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.
>>
>>
>> 3) Come time to propose the identity-api patch, there might be
>> differences in what was proposed in the spec.
>>
>> 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.
>>
>>
>>
>> Personally I'd be OK with just stating the HTTP method and the endpoint.
>> Thoughts?
>>
>> 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.
>>
>>
>>
>> Many apologies in advance for my pedantic-ness!
>>
>> Laziness*
>>
>> (lazy engineers are just more efficient)
>>
>>
>> Regards,
>>
>> * Steve Martinelli*
>> Software Developer - Openstack
>> Keystone Core Member
>> ------------------------------
>>  *Phone:* *1-905-413-2851* <1-905-413-2851>
>> * E-mail:* *stevemar at ca.ibm.com* <stevemar at ca.ibm.com>
>> 8200 Warden Ave
>> Markham, ON L6G 1C7
>> Canada
>>
>>
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> *OpenStack-dev at lists.openstack.org* <OpenStack-dev at lists.openstack.org>
>> *http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev*
>> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140707/0d50a635/attachment-0001.html>