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.
* 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".
* 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