Hi, everyone. I've been using the draft management spec to develop some command line tools[1], and I've got some questions and comments. These comments are based on working draft 8 of the spec[2].
Thanks,
Justin
---
# Use of AMQP application-properties
Given that values in AMQP 1.0 application properties cannot be lists or maps (yikes--I didn't know that), I feel it's inadvisable to use application properties to define requests. We'd be better off using properties in the message body. Otherwise, we'll have to define standard string encodings in every instance where we want to use a non-scalar type.
# Application properties and studlyCaps
The spec calls for studlyCaps for standard property names, whereas an earlier draft had hyphenated names. FWIW, I prefer the latter, since it’s in line with the core AMQP spec.
# QUERY and pagination
There doesn’t appear to be a way to query for the total count without fetching all the values. Without that, you can’t build a data efficient page-navigation UI that offers links to each page (or just the last page).
Requests using offset and count should perhaps instead use offset and “limit”. That’s more familiar to those who have used SQL, and it correctly signals that the number returned may be less than the number requested. In my view, the request should use “limit”, and the response should use “count”.
Also, if we’re doing paging we need to do sorting as well. Otherwise, A client UI cannot build a sortable paginated table without pulling down everything.
# Request-response
There’s a note in section 4 that multiple response messages may be produced for a single request. How should a client determine whether the response is complete?
# GET-MGMT-NODES
The text says the response message must contain “a list of addresses of other Management Nodes”. Perhaps this should more explicitly prohibit listing the currently-in-communication management node (or drop the word "other").
# [DE]REGISTER
What is the intended use of this? That is, what new behavior do you get when something is registered?
# Ping
I’d like to see a standard PING or ECHO operation on $management. I can simulate it by using an arbitrary operation, but that seems less than straightforward for implementors.
# Clerical stuff
3.3.3.1: Awkward phrasing: “so if any of the changes cannot be applied, the entire operation should not be applied and to multiple values changed this MUST result in a failure response”
3.4.1: Typo: “this operation supports pagination <though> which a request”
3.4.1: Awkward phrasing: “A result set of size N <can be considered to containing elements>”
# Odds and ends
- 2.3: Should this reference the AMQP definition of a “node”?
- 3.1: It would be nice to mention that locales is a comma-separated list. The RFC mentions it, but you have to dig down a bit.
-
3.3.1.2: What is a good example of a generic value made specific in an UPDATE response?
- 3.3.3: Is the lack of attribute append a problem? Right now, there is only replacing list values, and dueling actors could mean lost state.