Feedback from reading the spec

[bkrannich]

Here is a list of feedback I collected while re-reading the spec. I am willing to create PRs but I want to make sure people think this feedback is valid.

https://github.com/bkrannich/specification/blob/sm-ops/api.md#overview

• "defines an HTTP interface" - isn't that a REST interface, actually? If not, what prevents it from being one?
• SM abbreviation is used without being introduced (even if it is obvious)
• Same for CLI
• is all lowercase, with no spaces - dashes are allowed, right? Wondering if this is the right section to discuss this requirement.

https://github.com/bkrannich/specification/blob/sm-ops/api.md#creating-a-resource-entity

• Would it be helpful to have a resource returning all the resource entities known to the system and their LIST endpoint? E.g. for dynamic discovery?
• "Some APIs may allow passing in the resource entity id (that is the ID to be used to uniquely identify the resource entity) for backward compatibility reasons. If an id is not passed as part of the request body, the Service Manager takes care of generating one." - what happens if the ID is already assigned to some other entity?

https://github.com/bkrannich/specification/blob/sm-ops/api.md#body-3

• "* Fields with an asterisk are REQUIRED." - why does this appear at this stage in the document (and not earlier)?

https://github.com/bkrannich/specification/blob/sm-ops/api.md#resource-types

• Meta-comment: This section is rather lengthy for the fact that it "only" provides "forward pointers" to later sections of the document.

https://github.com/bkrannich/specification/blob/sm-ops/api.md#osb-management

• "and be registered as one in the platforms that are associated with it" -> "and be registered as service broker in the platforms that are associated with it"
• "When a request is send" -> "When a request is sent"