[occi-wg] Comments, Suggested Changes for Walkthrough

[Edmonds, AndrewX]

Hi all,
I've gone through the walk through and have a list of comments and suggested changes. I will be continuing on through the spec with a similar intention of contributing comments and suggested changes.

Thijs, if you like I can add these to the tracker unless you want to pre-process them?

I do not suggest discussing any of these via the mailing list. That discussion can happen via the issue tracker.

Andy


* General
   * Would be useful to introduce the notion of OCCI extensions in the walk through
   * A page break should be inserted to separate the walkthrough and "OCCI Core Specification"
   * Revise usage of brackets

* Paragraph 4 "resource or type of resource"
   * what's the difference here?

* Paragraph 4 "and search"
   * note that this is an extension and may not be supported in all implementations

* Paragraph 5 Bracket usage in the sentence "Certain types of accesses..."
   * would read better as: Certain types of accesses, such as a compute resource querying OCCI for introspection and configuration, may be possible anonymously in the case where the query has already been authenticated by interface and/or IP address.

* Paragraph 6 "Should you be redirected by the API to a node, storage device, etc. (for example, to retrieve a large binary representation) then you should either be able to transparently authenticate or a signed URL should be provided."
   * If the basic authentication is not cached then this transparent authentication will not happen. Is what I say a correct statement?

* Paragraph 6 "(at least not yet!)"
   * Remove this, not necessary.

* Paragraph 6 "and while OCCI standardises a number of them for interoperability"
   * We can only recommend other standards for use in OCCI not standardise them - that's the responsibility of the relevant standards body

* Paragraph 6 List of representations
   * I do not agree that a screenshot or access to console is an appropriate general entity representation like what OVF/OVA are. These items are more suitable as attributes in an entity representation (OVF/OVA/OCCI). Suggest removing or noting that they are lesser forms.

* Paragraph 7 "The client indicates which representation(s) it desires by way of the URL"
   * An example illustrating this might be useful e.g.
   * To request a HTML rendering, if supported, of a compute node issue http://example.com/path/to/compute/resource/123-123-123.html
   * The same might be for the content negotiation.

* Paragraph 8 "In addition to the protocol itself,"
   * Remove the protocol includes interaction semantics, syntax and data schemas.

* Paragraph 8 "In addition to the protocol itself, OCCI defines a simple key/value based descriptor format for cloud infrastructure resources:".
   * Reword to: "OCCI defines a simple key/value based descriptor format for cloud infrastructure resources. These infrastructure resources as defined by OCCI are:".

* Paragraph 8 Formatting
   * Embolden compute storage and network - these are core concepts to OCCI.

* Paragraph 9 Comment
   * If we say that it is trivial to translate and present an example that example should show the trivial translation. In this case we should add the XML and JSON examples.

* Paragraph 10 Starting "The primary drawback is that" ending "or HTTP 410 Gone otherwise)."
   * Is this necessary here -  might be better moved out of the walkthrough to elsewhere or just removed.

* Paragraph 10 Comment
   * Bracket usage should be reviewed.

* Paragraph 12 "UUIDs anyway"
   * Remove "anyway".

* Paragraph 12 "used instead (e.g. http://amazon.com/compute/ami-ef48af86)."
   * Any significance using this URL - better we use something fictional

* Paragraph 12 "can be safely allocated by any node"
   * What's a "node"? A resource? A resource manager?

* Section 2.3 Comment
   * A brief introduction should be inserted here.

* Paragraph 13 "POST it to"
   * What is "it"? Explicate.

* Paragraph 13 "as an HTML form"
   * More correct to say "POST the attributes and values using the application/x-www-form-urlencoded format"

* Paragraph 15 "to GET a template"
   * New concept introduced with no explanation. Explain briefly (footnote?) or drop and move discussion elsewhere in doc.

* Paragraph 15 "POST or PUT it back"
   * There are semantic differences here that should be noted to the reader.

* Paragraph 17 P18 Comment
   * It would make more sense to inform the user how to get a list of supported renders per provider first and then tell how to request it. As it initially reads it appears that 2 calls are needed.

* Paragraph 19 "There are two options:"
   * Better phrased as "There are two concepts that are supported"

* Paragraph 19 "such as searches"
   * Change to "such as the collections returned from the search extension"

* Paragraph 19 Pass-by-ref, pass-by-value
   * This is more a metaphor -  might be worth explaining what is meant by these explicitly, otherwise the reader is left to interpret.

* Paragraph 20 "Update"
   * It says to PUT but I can also update via POST and be naughty.

* Paragraph 22 Comment
   * What about "Resource Child Collections".

* Paragraph 22 Comment
   * These are in effect extensions to the core and so should be noted as such.

* Paragraph 24 "Requests"
   * Just a comment - isn't this very RPC-like something that REST aims to avoid?

* Paragraph 24 "Requests"
   * A number of request types are mentioned but nowhere in the spec are they detailed.


Andy Edmonds
skype: andy.edmonds
tweets: @dizz



-------------------------------------------------------------
Intel Ireland Limited (Branch)
Collinstown Industrial Park, Leixlip, County Kildare, Ireland
Registered Number: E902934

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.ogf.org/pipermail/occi-wg/attachments/20090930/63c98706/attachment.html