[openstack-dev] [Keystone] Documenting the V2 API

Anne Gentle anne at openstack.org
Sat Mar 2 04:56:48 UTC 2013


Hi guys, more below.


On Fri, Mar 1, 2013 at 10:04 PM, Dolph Mathews <dolph.mathews at gmail.com>wrote:

>
>
> On Friday, March 1, 2013, Adam Young wrote:
>
>> We currently list the V2 API as Beta.  Its time to change that.
>>
>> What do we need to do in order to make this legit?   Biggest thing I know
>> of is to document the token API.
>
>
> Our 300 Multiple Choice response indicates it's beta. It should have been
> stable for both Essex and Folsom. In light of v3, it should be considered
> deprecated instead.
>
>>
>> I have a task to document the additional calls for the PKI tokens. Those
>> are:
>>
>> GET /certificates/signing
>> and
>> GET /certificates/ca
>>
>> But I am not quite certain where to put the docs.
>>
>> The docs in keystone/docs/source Seem to be lacking.  There is the curl
>> example page:
>>
>> http://docs.openstack.org/**developer/keystone/api_curl_**
>> examples.html#id3<http://docs.openstack.org/developer/keystone/api_curl_examples.html#id3>
>>
>>
> Curl examples were originally written before there was a client. I think
> they can be killed soon.
>
>
>> I don't think what that returns is accurate.  We have a slew of Metatdata
>> things in the token now-a-days.
>>
>>
>> There is also the Identity API docs
>>
>> https://github.com/openstack/**identity-api/tree/master/**
>> openstack-identity-api/src/**docbkx<https://github.com/openstack/identity-api/tree/master/openstack-identity-api/src/docbkx>
>>
>> I have not yet identified what the state of the WADL is:
>>
>> https://github.com/openstack/**identity-api/blob/master/**
>> openstack-identity-api/src/**docbkx/admin/identity-admin.**wadl<https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/docbkx/admin/identity-admin.wadl>
>>
>>
>>
> The official documentation for v2 is this WADL and the referenced XSD's.
> there's a separate WADL for the public API.
>
>
>> What do we need to do documentation wise before Grizzly Goes GA?
>>
>> Also,  what will happen with the Markdown for the V3 API?  I've run an
>> HTML transform on it, and it looks very simplistic. I assume there is a
>> style sheet, but where is it?
>
>
> Anne asked us to write markdown because she had a plan for rendering it to
> either docs.openstack.org or api.openstack.org -- I assume the style
> sheets would live in one of those projects, not ours.
>
>
>>
>>
It's fine to write in markdown or docbook, the build jobs can support
markdown by turning it into docbook automatically. We have a script in
openstack-infra/config:
/modules/jenkins/files/slave_scripts/markdown-docbook.sh

But right now the 2 or 3 markdown files we have aren't using it, and that
needs investigation. Other markdown files are the api programming guide and
the Image API v2. Bug logged:
https://bugs.launchpad.net/openstack-manuals/+bug/1139231

A bit too tired from the book sprint to dig further but that might get you
on the right track to build your v3 with more styling.
Anne


>
>>
>>
>> ______________________________**_________________
>> OpenStack-dev mailing list
>> 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>
>>
>
>
> --
>
> -Dolph
>
> _______________________________________________
> 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/20130301/d7751466/attachment.html>


More information about the OpenStack-dev mailing list