[openstack-dev] [keystone][specs] listing the entire API in a new spec

Anne Gentle anne at openstack.org
Mon Jul 7 19:51:41 UTC 2014


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.

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?

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140707/54a395da/attachment.html>


More information about the OpenStack-dev mailing list