Attached are my comments on draft 15.
Sorry, but I couldn't resist the urge to suggest a few changes to the
protocol. But they're relatively minor.
- Wendy Roome
Comments on ALTO draft 15. Page numbers are from the PDF version.
Suggested changes or extensions:
{9.2} Version Tag:
How about saying that vtags should start with a string that's unique
to the ALTO service provider, such as an IP address or a domain name
owned by the ALTO provider? The reason is to ensure that two
unrelated ALTO servers don't accidentally use the same vtag.
{9.6} Cost Type structure and IRD meta in {8.5.3}:
How about adding a "consistent-with" item in the IRD metadata
with a list of IRD URIs for ALTO servers that are consistent
with this server? "Consistent" means they use the same network map,
and if they provide the same cost-metrics or properties, they'll
have the same values.
Eg,
"meta" : {
"costâtypes": {
"numârouting": {...},
"numâhop": {...}
"ordârouting": {...},
"ordâhop": {...}
},
"consistent-with": [
"http://custom.alto.example.com/maps";
]
},
{8.5.3} & {8.5.4} IRD examples
{8.5.3} gives an example of one IRD pointing to another ALTO server.
The first IRD gives a superset of the "media-types" and "accepts"
for the services at the other ALTO server. {8.5.4} then shows how
to use an OPTIONS request to get the details from the second server.
I suggest simplifying that. Instead of the first IRD trying to give
a summary of the services on the second IRD, the first ALTO server
just has an entry with the URI of the IRD of the other ALTO server,
and the single media-type "application/altoâdirectory+json" to
indicate
that this URI returns an IRD.
Then for {8.5.4}, delete all of the text at the top explaining about
the 300/Multiple Choices status codes. Just say that the client
discovers
the services from the other URI by doing another GET for that IRD.
Eg, the {8.5.3} example becomes:
}, {
"uri" : "http://custom.alto.example.com/maps";,
"mediaâtypes" : ["application/altoâdirectory+json"]
}, {
And {8.5.4} becomes a GET instead of an OPTIONS request:
8.5.4 Another Example
The ALTO Client can discover the maps available at
"custom.alto.example.com"
by successfully performing a GET request to
"http://custom.alto.example.com/maps":
GET /maps HTTP/1.1
Host: custom.alto.example.com
Accept:
application/altoâdirectory+json,application/altoâerror+json
HTTP/1.1 200 OK
ContentâLength: TBA
ContentâType: application/altoâdirectory+json
{
"meta" : {
costâtypes": {
"numârouting": {...},
"numâhop": {...}
"ordârouting": {...},
"ordâhop": {...}
},
"consistent-with": [
"http://alto.example.com/directory";
]
},
"resources": [
....
]
}
NOTE: This then begs the question of why do "media-types" and "accepts"
need to be
arrays? Is there ever a reason for having more than one media-type or
accepts
for one entry? If a URI does accept two different filtered services,
and distinguishes them by the media type for the POST data sent by
the client, just use two different entries in the IRD with the same URI.
{10.4.1.3}, p51-52, Endpoint Cost Parameters
Currently it says to use the client's address if the source list is
omitted.
How about extending that slightly:
If the list of Source or Destination Endpoints is missing (or not
included),
the ALTO Server MUST interpret the missing list as if it contained
the Endpoint Address corresponding to the client IP address .....
The Source and Destination Endpoint lists MUST NOT both be empty.
FYI -- in most of the use cases I've worked on, the client is the
destination.
Eg, I use ALTO to find the best server from which to download a movie.
Typos:
p18, next to last paragraph: "memerbs" => "members"
p18, next to last paragraph: Currently it says
and an array is indicated by two numbers, m and n,
where m indicates the minimal number of values, and n is the maximum.
When we write .. for n, it means no upper bound.
That doesn't match the usage. How about replacing that with
and an array is indicated by two numbers in angle brackets, <m..n>,
where m indicates the minimal number of values, and n is the maximum.
When we write * for n, it means no upper bound.
p23, {8.5.3}: This is about an Information Resource Directory or "IRD".
So why use "IDR" as a prefix in "IDRMeta" and "IDRResourceEntry"?
Wouldn't it make more sense to call those objects IDRMeta and
IRDResourceEntry?
p23-25:
There's no definition of the cost-types attribute in the IRD metadata;
it's only defined by example. {9.6} does define a CostType structure,
but that CostType does not include the "description" field used in
the IRD examples. My guess is that we want the {9.6} CostType object
to only apply to map queries and responses; the items in the IRD meta
cost-types
list are of a different type.
So that should be defined in {8.5.2}.
Or if cost-types really is a list of {9.6} CostType objects,
drop the "description" fields from the examples, and give a
forward reference to {9.6}.
p25, top of page: "Resoucres" => "Resources".
A few lines down, there's
... from the "meta" member of the IDR.
Shouldn't the acronym be "IRD"?
What about moving the definition of the CostType object from {9.6} to
{8.5.2}?
As it stands now, the example on p25 gives cost-types without an
explanation,
which is confusing to the reader. Or at least give a forward-reference
to {9.6}.
p26, {8.5.4}:
The comments about "may indicate multiple IRDs with one ALTO endpoint"
are inconsistent with the example, because
"http://custom.alto.example.con/maps";
does NOT provide multiple services. Instead, that URI returns an IRD.
According to the example, the filtered services are provided by
different
uris.
p29, {8.6}:
Didn't we say that that "meta" item was optional?
p35, {9.5} Cost Metrics:
Didn't this used to say that "." in a cost metric name was legal
but reserved for future use?
p36, {9.6} Cost Type
See earlier comments about whether this is the type of JSON objects
in the IRD meta cost-types list. If it is, and you want to retain
the "description" field, define it here, and indicate that it's
optional.
p48 - 49, {10.3.1.4}
Currently it has "prop-types<0..*>". Shouldn't that be <1..*>?
It seems silly to have an endpoint prop service that doesn't have
any properties. Assuming you make that change, at the top of
page 49, drop the sentence,
If not present, this member MUST be interpreted as an empty
array.
p64-67:
There are several cross-refs that show up as <xref target="...">,
at least in the PDF version.
- Wendy Roome
_______________________________________________
alto mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/alto
