Open Stack

On 5/24/2017 10:05 AM, Mathieu Gagné wrote:
> 
> * There a multiple supported config drive versions (2012-08-10, ..., 
> 2017-02-22) so we need to document them all.

Yeah, but there are a lot of microversions in the compute REST API too 
and we document each one - it's just easier since we made it a rule from 
the start, so we have catching up to do with the metadata API versions.

> * How do we plan on making it easy for someone to understand which 
> fields will be available in each versions?

I think we'd do something like with the compute REST API reference, 
which says nothing for the base version (2.1 in that case), but denotes 
when a new field is added in a new version, e.g. the image_id field in 
the createImage server action response [1].

> * If a field is removed, how will it be expressed in the documentation?

Similar to the compute API reference, we note in the table when it's 
deprecated (meaning it's no longer there in versions after that). See 
the Location header in the response table for [1].

> * Could a field change type in the future? (object vs list of objects 
> for example)

Possibly, but hopefully we'd avoid that since it's not easy to document 
or use when that happens.

> * The idea of a documentation similar to the REST API version history is 
> good. I however wouldn't have the patience to mentally "compute" the 
> resulting config drive. So I think we need both (history + schema/examples).

Yes, that's what I'm proposing, and is what we have for the compute REST 
API, but in different locations [2][3].

> * We should document the purpose of each field and how a user can 
> populate or use that field. For example, I have no idea what's the 
> purpose of the "launch_index" field but I suspect it's related to the 
> --max-count parameter with nova boot command.

Agree, we'd have a table for the parameters in a response similar to the 
compute REST API reference with a description and some metadata about 
each one, i.e. type, optional/required, possible values, etc.

[1] 
https://developer.openstack.org/api-ref/compute/?expanded=create-image-createimage-action-detail#create-image-createimage-action
[2] https://docs.openstack.org/developer/nova/api_microversion_history.html
[3] https://developer.openstack.org/api-ref/compute/

-- 

Thanks,

Matt