I sent this out a few days ago, but it never hit the reflector. I should have realized, I wasn't flamed... :)

-gary

Hi,

I've been looking at the API document over the past couple of days and have some ideas I would like to float by the api team that may help it along its path to completion.

I don't have a bunch of time, apologies for the terseness. I would just like to get them down so we can mull them about.

-gary

Overall strategy:
Split the document into 4 parts:
    1) a FAQ
    2) the walkthough (which an Atom version is already in a white paper of sorts)
    3) The core API document which included front matter; the description of the IaaS model components and a description and organization of datum (taxonomy); state diagram & states; the APIs based on CRUD operations including verbs and associated data; and completion codes
    4) Mapping to the different API formats, ie, Atom, JSON, text and whatever else someone would want. The mapping document includes mapping of data to XML, CRUD verbs to HTTP operations and mapping of completion codes. This also included the methodology for connection, authentication, implementation specific data formats and representations.

Details

1) Section 2: Move to White paper
2) Section 3: Move to FAQ
3) Section 4.3.1. Atom XML: Move to Atom Mapping specification
4) Section 4.3.2. Plain Text: Move to Plain Text Mapping specification
5) Section 4.3.3. JSON: Move to JSON Mapping specification
6) Section 4.5. References: Move to front matter "Normative References"
7) Section 4.6.1. IANA Considerations: Move to Appendix
8) Section 4.6.1. 6. OCCI Registries: Remove HTTP numerations and shift them to the appropriate mapping specification
9) New Appendix for Conformance : Extensions defined in sections 4.4 and 5.2 implies ans states level of conformance. A list of operations and data supported for levels of conformance needs to be defined.
10) Much of the operations are written around HTTP atom. This needs to be more generic.

Definitions Required (in alphabetical order):

Asynchronous operation

Atom XML

Average rate of progress