RFC 7285
Application-Layer Traffic Optimization (ALTO) Protocol
10. Protocol Specification: Basic Data Types
This section details the format of basic data types.10.1. PID Name
A PID Name is encoded as a JSON string. The string MUST be no more than 64 characters, and it MUST NOT contain characters other than US- ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), the at sign ('@', code point U+0040), the low line ('_', U+005F), or the '.' separator (U+002E). The '.' separator is reserved for future use and MUST NOT be used unless specifically indicated in this document, or an extension document. The type PIDName is used in this document to indicate a string of this format.10.2. Resource ID
A resource ID uniquely identifies a particular resource (e.g., an ALTO network map) within an ALTO server (see Section 9.2). A resource ID is encoded as a JSON string with the same format as that of the type PIDName. The type ResourceID is used in this document to indicate a string of this format.10.3. Version Tag
A version tag is defined as: object { ResourceID resource-id; JSONString tag; } VersionTag;
As described in Section 6.3, the "resource-id" field provides the resource ID of a resource (e.g., a network map) defined in the information resource directory, and "tag" provides an identifier string. Two version tags are equal if and only if both the "resource-id" fields are byte-for-byte equal and the "tag" fields are byte-for-byte equal. A string representing the "tag" field MUST be no more than 64 characters, and it MUST NOT contain any character below U+0021 or above U+007E. It is RECOMMENDED that the "tag" string have a low collision probability with other tags. One suggested mechanism is to compute it using a hash of the data contents of the resource.10.4. Endpoints
This section defines formats used to encode addresses for endpoints. In a case that multiple textual representations encode the same endpoint address or prefix (within the guidelines outlined in this document), the ALTO Protocol does not require ALTO clients or ALTO servers to use a particular textual representation, nor does it require that ALTO servers reply to requests using the same textual representation used by requesting ALTO clients. ALTO clients must be cognizant of this.10.4.1. Typed Endpoint Addresses
When an endpoint address is used, an ALTO implementation must be able to determine its type. For this purpose, the ALTO Protocol allows endpoint addresses to also explicitly indicate their types. This document refers to such addresses as "Typed Endpoint Addresses". Typed endpoint addresses are encoded as strings of the format AddressType:EndpointAddr, with the ':' character as a separator. The type TypedEndpointAddr is used to indicate a string of this format.10.4.2. Address Type
The AddressType component of TypedEndPointAddr is defined as a string consisting of only US-ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A). The type AddressType is used in this document to indicate a string of this format.
This document defines two values for AddressType: "ipv4" to refer to IPv4 addresses and "ipv6" to refer to IPv6 addresses. All AddressType identifiers appearing in an HTTP request or response with an "application/alto-*" media type MUST be registered in the "ALTO Address Type Registry" (see Section 14.4).10.4.3. Endpoint Address
The EndpointAddr component of TypedEndPointAddr is also encoded as a string. The exact characters and format depend on AddressType. This document defines EndpointAddr when AddressType is "ipv4" or "ipv6".10.4.3.1. IPv4
IPv4 Endpoint Addresses are encoded as specified by the IPv4address rule in Section 3.2.2 of [RFC3986].10.4.3.2. IPv6
IPv6 endpoint addresses are encoded as specified in Section 4 of [RFC5952].10.4.4. Endpoint Prefixes
For efficiency, it is useful to denote a set of endpoint addresses using a special notation (if one exists). This specification makes use of the prefix notations for both IPv4 and IPv6 for this purpose. Endpoint prefixes are encoded as strings. The exact characters and format depend on the type of endpoint address. The type EndpointPrefix is used in this document to indicate a string of this format.10.4.4.1. IPv4
IPv4 endpoint prefixes are encoded as specified in Section 3.1 of [RFC4632].10.4.4.2. IPv6
IPv6 endpoint prefixes are encoded as specified in Section 7 of [RFC5952].
10.4.5. Endpoint Address Group
The ALTO Protocol includes messages that specify potentially large sets of endpoint addresses. Endpoint address groups provide a more efficient way to encode such sets, even when the set contains endpoint addresses of different types. An endpoint address group is defined as: object-map { AddressType -> EndpointPrefix<0..*>; } EndpointAddrGroup; In particular, an endpoint address group is a JSON object representing a map, where each key is the string corresponding to an address type, and the corresponding value is an array listing prefixes of addresses of that type. The following is an example with both IPv4 and IPv6 endpoint addresses: { "ipv4": [ "192.0.2.0/24", "198.51.100.0/25" ], "ipv6": [ "2001:db8:0:1::/64", "2001:db8:0:2::/64" ] }10.5. Cost Mode
A cost mode is encoded as a string. The string MUST have a value of either "numerical" or "ordinal". The type CostMode is used in this document to indicate a string of this format.
10.6. Cost Metric
A cost metric is encoded as a string. The string MUST be no more than 32 characters, and it MUST NOT contain characters other than US- ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), the low line ('_', U+005F), or the '.' separator (U+002E). The '.' separator is reserved for future use and MUST NOT be used unless specifically indicated by a companion or extension document. Identifiers prefixed with "priv:" are reserved for Private Use [RFC5226] without a need to register with IANA. All other identifiers that appear in an HTTP request or response with an "application/alto-*" media type and indicate cost metrics MUST be registered in the "ALTO Cost Metric Registry" Section 14.2. For an identifier with the "priv:" prefix, an additional string (e.g., company identifier or random string) MUST follow (i.e., "priv:" only is not a valid identifier) to reduce potential collisions. The type CostMetric is used in this document to indicate a string of this format.10.7. Cost Type
The combination of CostMetric and CostMode defines the type CostType: object { CostMetric cost-metric; CostMode cost-mode; [JSONString description;] } CostType; The "description" field, if present, MUST provide a string value with a human-readable description of the cost-metric and cost-mode. An ALTO client MAY present this string to a developer, as part of a discovery process; however, the field is not intended to be interpreted by an ALTO client.10.8. Endpoint Property
This document distinguishes two types of endpoint properties: resource-specific endpoint properties and global endpoint properties. The type EndpointPropertyType is used in this document to indicate a string denoting either a resource-specific endpoint property or a global endpoint property.
10.8.1. Resource-Specific Endpoint Properties
The name of resource-specific endpoint property MUST follow this format: a resource ID, followed by the '.' separator (U+002E), followed by a name obeying the same rules as for global endpoint property names (Section 10.8.2). This document defines only one resource-specific endpoint property: pid. An example is "my-default-networkmap.pid".10.8.2. Global Endpoint Properties
A global endpoint property is encoded as a string. The string MUST be no more than 32 characters, and it MUST NOT contain characters other than US-ASCII alphanumeric characters (U+0030-U+0039, U+0041-U+005A, and U+0061-U+007A), the hyphen ('-', U+002D), the colon (':', U+003A), or the low line ('_', U+005F). Note that the '.' separator is not allowed so that there is no ambiguity on whether an endpoint property is global or resource specific. Identifiers prefixed with "priv:" are reserved for Private Use [RFC5226] without a need to register with IANA. All other identifiers for endpoint properties appearing in an HTTP request or response with an "application/alto-*" media type MUST be registered in the "ALTO Endpoint Property Type Registry" Section 14.3. For an endpoint property identifier with the "priv:" prefix, an additional string (e.g., company identifier or random string) MUST follow (i.e., "priv:" only is not a valid endpoint property identifier) to reduce potential collisions.11. Protocol Specification: Service Information Resources
This section documents the individual information resources defined to provide the services defined in this document.11.1. Meta Information
For the "meta" field of the response to an individual information resource, this document defines two generic fields: the "vtag" field, which provides the version tag (see Section 10.3) of the current information resource, and the "dependent-vtags" field, which is an array of version tags, to indicate the version tags of the resources on which this resource depends.11.2. Map Service
The Map Service provides batch information to ALTO clients in the form of two types of maps: ALTO network maps and ALTO cost maps.
11.2.1. Network Map
An ALTO network map information resource defines a set of PIDs, and for each PID, lists the network locations (endpoints) within the PID. An ALTO server MUST provide at least one network map.11.2.1.1. Media Type
The media type of ALTO network maps is "application/alto- networkmap+json".11.2.1.2. HTTP Method
An ALTO network map resource is requested using the HTTP GET method.11.2.1.3. Accept Input Parameters
None.11.2.1.4. Capabilities
None.11.2.1.5. Uses
None.11.2.1.6. Response
The "meta" field of an ALTO network map response MUST include the "vtag" field, which provides the version tag of the retrieved network map. The data component of an ALTO network map response is named "network- map", which is a JSON object of type NetworkMapData: object { NetworkMapData network-map; } InfoResourceNetworkMap : ResponseEntityBase; object-map { PIDName -> EndpointAddrGroup; } NetworkMapData;
Specifically, a NetworkMapData object is a dictionary map keyed by PIDs. The value of each PID is the associated set of endpoint addresses for the PID. The returned network map MUST include all PIDs known to the ALTO server.11.2.1.7. Example
GET /networkmap HTTP/1.1 Host: alto.example.com Accept: application/alto-networkmap+json,application/alto-error+json HTTP/1.1 200 OK Content-Length: 449 Content-Type: application/alto-networkmap+json { "meta" : { "vtag": { "resource-id": "my-default-network-map", "tag": "da65eca2eb7a10ce8b059740b0b2e3f8eb1d4785" } }, "network-map" : { "PID1" : { "ipv4" : [ "192.0.2.0/24", "198.51.100.0/25" ] }, "PID2" : { "ipv4" : [ "198.51.100.128/25" ] }, "PID3" : { "ipv4" : [ "0.0.0.0/0" ], "ipv6" : [ "::/0" ] } } }
When parsing an ALTO network map, an ALTO client MUST ignore any EndpointAddressGroup whose address type it does not recognize. If as a result a PID does not have any address types known to the client, the client still MUST recognize that PID name as valid, even though the PID then contains no endpoints. Note that the encoding of an ALTO network map response was chosen for readability and compactness. If lookup efficiency at runtime is crucial, then the returned network map can be transformed into data structures offering more efficient lookup. For example, one may store an ALTO network map as a trie-based data structure, which may allow efficient longest-prefix matching of IP addresses.11.2.2. Mapping IP Addresses to PIDs for 'ipv4'/'ipv6' Network Maps
A key usage of an ALTO network map is to map endpoint addresses to PIDs. For network maps containing the "ipv4" and "ipv6" address types defined in this document, when either an ALTO client or an ALTO server needs to compute the mapping from IP addresses to PIDs, the longest-prefix matching algorithm (Longest Match in Section 5.2.4.3 of [RFC1812]) MUST be used. To ensure that the longest-prefix matching algorithm yields one and only one PID, an ALTO network map containing the "ipv4"/"ipv6" address types MUST satisfy the following two requirements. First, such a network map MUST define a PID for each possible address in the IP address space for all of the address types contained in the map. This is defined as the completeness property of an ALTO network map. A RECOMMENDED way to satisfy this property is to define a PID with the shortest enclosing prefix of the addresses provided in the map. For a map with full IPv4 reachability, this would mean including the 0.0.0.0/0 prefix in a PID; for full IPv6 reachability, this would be the ::/0 prefix. Second, such a network map MUST NOT define two or more PIDs that contain an identical IP prefix, in order to ensure that the longest- prefix matching algorithm maps each IP addresses into exactly one PID. This is defined as the non-overlapping property of an ALTO network map. Specifically, to map an IP address to its PID in a non- overlapping network map, one considers the set S, which consists of all prefixes defined in the network map, applies the longest-prefix mapping algorithm to S to identify the longest prefix containing the IP address and assigns that prefix the IP address belonging to the PID containing the identified longest prefix.
The following example shows a complete and non-overlapping ALTO
network map:
"network-map" : {
"PID0" : { "ipv6" : [ "::/0" ] },
"PID1" : { "ipv4" : [ "0.0.0.0/0" ] },
"PID2" : { "ipv4" : [ "192.0.2.0/24", "198.51.100.0/24" ] },
"PID3" : { "ipv4" : [ "192.0.2.0/25", "192.0.2.128/25" ] }
}
The IP address 192.0.2.1 should be mapped to PID3.
If, however, the two adjacent prefixes in PID3 were combined as a
single prefix, then PID3 was changed to:
"PID3" : { "ipv4" : [ "192.0.2.0/24" ] }
The new map is no longer non-overlapping, and 192.0.2.1 could no
longer be mapped unambiguously to a PID by means of longest-prefix
matching.
Extension documents may define techniques to allow a single IP
address being mapped to multiple PIDs, when a need is identified.
11.2.3. Cost Map
An ALTO cost map resource lists the path cost for each pair of
source/destination PIDs defined by the ALTO server for a given cost
metric and cost mode. This resource MUST be provided for at least
the "routingcost" cost metric.
11.2.3.1. Media Type
The media type of ALTO cost maps is "application/alto-costmap+json".
11.2.3.2. HTTP Method
An ALTO cost map resource is requested using the HTTP GET method.
11.2.3.3. Accept Input Parameters
None.
11.2.3.4. Capabilities
The capabilities of an ALTO server URI providing an unfiltered cost map is a JSON object of type CostMapCapabilities: object { JSONString cost-type-names<1..1>; } CostMapCapabilities; with field: cost-type-names: Note that the array MUST include a single CostType name defined by the "cost-types" field in the "meta" field of the IRD. This is because an unfiltered cost map (accept == "") is requested via an HTTP GET that accepts no input parameters. As a contrast, for filtered cost maps (see Section 11.3.2), the array can have multiple elements.11.2.3.5. Uses
The resource ID of the network map based on which the cost map will be defined. Recall (Section 6) that the combination of a network map and a cost type defines a key. In other words, an ALTO server MUST NOT define two cost maps with the same cost type / network map pair.11.2.3.6. Response
The "meta" field of a cost map response MUST include the "dependent- vtags" field, whose value is a single-element array to indicate the version tag of the network map used, where the network map is specified in "uses" of the IRD. The "meta" MUST also include the "cost-type" field, whose value indicates the cost type (Section 10.7) of the cost map.
The data component of a cost map response is named "cost-map", which
is a JSON object of type CostMapData:
object {
CostMapData cost-map;
} InfoResourceCostMap : ResponseEntityBase;
object-map {
PIDName -> DstCosts;
} CostMapData;
object-map {
PIDName -> JSONValue;
} DstCosts;
Specifically, a CostMapData object is a dictionary map object, with
each key being the PIDName string identifying the corresponding
source PID, and value being a type of DstCosts, which denotes the
associated costs from the source PID to a set of destination PIDs
(Section 6.2). An implementation of the protocol in this document
SHOULD assume that the cost is a JSONNumber and fail to parse if it
is not, unless the implementation is using an extension to this
document that indicates when and how costs of other data types are
signaled.
The returned cost map MUST include the path cost for each (source
PID, destination PID) pair for which a path cost is defined. An ALTO
server MAY omit entries for which path costs are not defined (e.g.,
either the source or the destination PIDs contain addresses outside
of the network provider's administrative domain).
Similar to the encoding of ALTO network maps, the encoding of ALTO
cost maps was chosen for readability and compactness. If lookup
efficiency at runtime is crucial, then the returned cost map can be
transformed into data structures offering more efficient lookup. For
example, one may store a cost map as a matrix.
11.2.3.7. Example
GET /costmap/num/routingcost HTTP/1.1 Host: alto.example.com Accept: application/alto-costmap+json,application/alto-error+json HTTP/1.1 200 OK Content-Length: 435 Content-Type: application/alto-costmap+json { "meta" : { "dependent-vtags" : [ {"resource-id": "my-default-network-map", "tag": "3ee2cb7e8d63d9fab71b9b34cbf764436315542e" } ], "cost-type" : {"cost-mode" : "numerical", "cost-metric": "routingcost" } }, "cost-map" : { "PID1": { "PID1": 1, "PID2": 5, "PID3": 10 }, "PID2": { "PID1": 5, "PID2": 1, "PID3": 15 }, "PID3": { "PID1": 20, "PID2": 15 } } } Similar to the network map case, array-based encoding for "map" was considered, but the current encoding was chosen for clarity.11.3. Map-Filtering Service
The Map-Filtering Service allows ALTO clients to specify filtering criteria to return a subset of a full map available in the Map Service.11.3.1. Filtered Network Map
A filtered ALTO network map is an ALTO network map information resource (Section 11.2.1) for which an ALTO client may supply a list of PIDs to be included. A filtered ALTO network map MAY be provided by an ALTO server.
11.3.1.1. Media Type
Since a filtered ALTO network map is still an ALTO network map, it uses the media type defined for ALTO network maps at Section 11.2.1.1.11.3.1.2. HTTP Method
A filtered ALTO network map is requested using the HTTP POST method.11.3.1.3. Accept Input Parameters
An ALTO client supplies filtering parameters by specifying media type "application/alto-networkmapfilter+json" with HTTP POST body containing a JSON object of type ReqFilteredNetworkMap, where: object { PIDName pids<0..*>; [AddressType address-types<0..*>;] } ReqFilteredNetworkMap; with fields: pids: Specifies list of PIDs to be included in the returned filtered network map. If the list of PIDs is empty, the ALTO server MUST interpret the list as if it contained a list of all currently defined PIDs. The ALTO server MUST interpret entries appearing multiple times as if they appeared only once. address-types: Specifies a list of address types to be included in the returned filtered network map. If the "address-types" field is not specified, or the list of address types is empty, the ALTO server MUST interpret the list as if it contained a list of all address types known to the ALTO server. The ALTO server MUST interpret entries appearing multiple times as if they appeared only once.11.3.1.4. Capabilities
None.11.3.1.5. Uses
The resource ID of the network map based on which the filtering is performed.
11.3.1.6. Response
The format is the same as unfiltered network maps. See Section 11.2.1.6 for the format. The ALTO server MUST only include PIDs in the response that were specified (implicitly or explicitly) in the request. If the input parameters contain a PID name that is not currently defined by the ALTO server, the ALTO server MUST behave as if the PID did not appear in the input parameters. Similarly, the ALTO server MUST only enumerate addresses within each PID that have types specified (implicitly or explicitly) in the request. If the input parameters contain an address type that is not currently known to the ALTO server, the ALTO server MUST behave as if the address type did not appear in the input parameters. The version tag included in the "vtag" field of the response MUST correspond to the full (unfiltered) network map information resource from which the filtered information is provided. This ensures that a single, canonical version tag is used independent of any filtering that is requested by an ALTO client.
11.3.1.7. Example
POST /networkmap/filtered HTTP/1.1 Host: custom.alto.example.com Content-Length: 33 Content-Type: application/alto-networkmapfilter+json Accept: application/alto-networkmap+json,application/alto-error+json { "pids": [ "PID1", "PID2" ] } HTTP/1.1 200 OK Content-Length: 342 Content-Type: application/alto-networkmap+json { "meta" : { "vtag" : { "resource-id": "my-default-network-map", "tag": "c0ce023b8678a7b9ec00324673b98e54656d1f6d" } }, "network-map" : { "PID1" : { "ipv4" : [ "192.0.2.0/24", "198.51.100.0/24" ] }, "PID2" : { "ipv4": [ "198.51.100.128/24" ] } } }11.3.2. Filtered Cost Map
A filtered ALTO cost map is a cost map information resource (Section 11.2.3) for which an ALTO client may supply additional parameters limiting the scope of the resulting cost map. A filtered ALTO cost map MAY be provided by an ALTO server.
11.3.2.1. Media Type
Since a filtered ALTO cost map is still an ALTO cost map, it uses the media type defined for ALTO cost maps at Section 11.2.3.1.11.3.2.2. HTTP Method
A filtered ALTO cost map is requested using the HTTP POST method.11.3.2.3. Accept Input Parameters
The input parameters for a filtered cost map are supplied in the entity body of the POST request. This document specifies the input parameters with a data format indicated by the media type "application/alto-costmapfilter+json", which is a JSON object of type ReqFilteredCostMap, where: object { CostType cost-type; [JSONString constraints<0..*>;] [PIDFilter pids;] } ReqFilteredCostMap; object { PIDName srcs<0..*>; PIDName dsts<0..*>; } PIDFilter; with fields: cost-type: The CostType (Section 10.7) for the returned costs. The "cost-metric" and "cost-mode" fields MUST match one of the supported cost types indicated in this resource's "capabilities" field (Section 11.3.2.4). The ALTO client SHOULD omit the "description" field, and if present, the ALTO server MUST ignore the "description" field. constraints: Defines a list of additional constraints on which elements of the cost map are returned. This parameter MUST NOT be specified if this resource's "capabilities" field (Section 11.3.2.4) indicate that constraint support is not available. A constraint contains two entities separated by whitespace: (1) an operator, "gt" for greater than, "lt" for less than, "ge" for greater than or equal to, "le" for less than or equal to, or "eq" for equal to and (2) a target cost value. The cost value is a number that MUST be defined in the same units as
the cost metric indicated by the "cost-metric" parameter. ALTO
servers SHOULD use at least IEEE 754 double-precision floating
point [IEEE.754.2008] to store the cost value, and SHOULD perform
internal computations using double-precision floating-point
arithmetic. If multiple "constraint" parameters are specified,
they are interpreted as being related to each other with a logical
AND.
pids: A list of source PIDs and a list of destination PIDs for which
path costs are to be returned. If a list is empty, the ALTO
server MUST interpret it as the full set of currently defined
PIDs. The ALTO server MUST interpret entries appearing in a list
multiple times as if they appeared only once. If the "pids" field
is not present, both lists MUST be interpreted by the ALTO server
as containing the full set of currently defined PIDs.
11.3.2.4. Capabilities
The URI providing this resource supports all capabilities documented
in Section 11.2.3.4 (with identical semantics), plus additional
capabilities. In particular, the capabilities are defined by a JSON
object of type FilteredCostMapCapabilities:
object {
JSONString cost-type-names<1..*>;
JSONBool cost-constraints;
} FilteredCostMapCapabilities;
with fields:
cost-type-names: See Section 11.2.3.4 and note that the array can
have one to many cost types.
cost-constraints: If true, then the ALTO server allows cost
constraints to be included in requests to the corresponding URI.
If not present, this field MUST be interpreted as if it specified
false. ALTO clients should be aware that constraints may not have
the intended effect for cost maps with the ordinal cost mode since
ordinal costs are not restricted to being sequential integers.
11.3.2.5. Uses
The resource ID of the network map based on which the cost map will
be filtered.
11.3.2.6. Response
The format is the same as an unfiltered ALTO cost map. See Section 11.2.3.6 for the format. The "dependent-vtags" field in the "meta" field provides an array consisting of a single element, which is the version tag of the network map used in filtering. ALTO clients should verify that the version tag included in the response is equal to the version tag of the network map used to generate the request (if applicable). If it is not, the ALTO client may wish to request an updated network map, identify changes, and consider requesting a new filtered cost map. The returned cost map MUST contain only source/destination pairs that have been indicated (implicitly or explicitly) in the input parameters. If the input parameters contain a PID name that is not currently defined by the ALTO server, the ALTO server MUST behave as if the PID did not appear in the input parameters. If any constraints are specified, source/destination pairs for which the path costs do not meet the constraints MUST NOT be included in the returned cost map. If no constraints were specified, then all path costs are assumed to meet the constraints.
11.3.2.7. Example
POST /costmap/filtered HTTP/1.1 Host: custom.alto.example.com Content-Type: application/alto-costmapfilter+json Content-Length: 181 Accept: application/alto-costmap+json,application/alto-error+json { "cost-type" : {"cost-mode": "numerical", "cost-metric": "routingcost" }, "pids" : { "srcs" : [ "PID1" ], "dsts" : [ "PID1", "PID2", "PID3" ] } } HTTP/1.1 200 OK Content-Length: 341 Content-Type: application/alto-costmap+json { "meta" : { "dependent-vtags" : [ {"resource-id": "my-default-network-map", "tag": "75ed013b3cb58f896e839582504f622838ce670f" } ], "cost-type": {"cost-mode" : "numerical", "cost-metric" : "routingcost" } }, "cost-map" : { "PID1": { "PID1": 0, "PID2": 1, "PID3": 2 } } }11.4. Endpoint Property Service
The Endpoint Property Service provides information about endpoint properties to ALTO clients.
11.4.1. Endpoint Property
An endpoint property resource provides information about properties for individual endpoints. In addition to the required "pid" endpoint property (see Sections 7.1.1 and 11.4.1.4), further endpoint properties MAY be provided by an ALTO server.11.4.1.1. Media Type
The media type of an endpoint property resource is "application/ alto-endpointprop+json".11.4.1.2. HTTP Method
The endpoint property resource is requested using the HTTP POST method.11.4.1.3. Accept Input Parameters
The input parameters for an endpoint property request are supplied in the entity body of the POST request. This document specifies the input parameters with a data format indicated by the media type "application/alto-endpointpropparams+json", which is a JSON object of type ReqEndpointProp: object { EndpointPropertyType properties<1..*>; TypedEndpointAddr endpoints<1..*>; } ReqEndpointProp; with fields: properties: List of endpoint properties to be returned for each endpoint. Each specified property MUST be included in the list of supported properties indicated by this resource's "capabilities" field (Section 11.4.1.4). The ALTO server MUST interpret entries appearing multiple times as if they appeared only once. endpoints: List of endpoint addresses for which the specified properties are to be returned. The ALTO server MUST interpret entries appearing multiple times as if they appeared only once.11.4.1.4. Capabilities
The capabilities of an ALTO server URI providing endpoint properties are defined by a JSON object of type EndpointPropertyCapabilities:
object {
EndpointPropertyType prop-types<1..*>;
} EndpointPropertyCapabilities;
with field:
prop-types: The endpoint properties (see Section 10.8) supported by
the corresponding URI.
In particular, the information resource closure MUST provide the
lookup of pid for every ALTO network map defined.
11.4.1.5. Uses
None.
11.4.1.6. Response
The "dependent-vtags" field in the "meta" field of the response MUST
be an array that includes the version tags of all ALTO network maps
whose "pid" is queried.
The data component of an endpoint properties response is named
"endpoint-properties", which is a JSON object of type
EndpointPropertyMapData, where:
object {
EndpointPropertyMapData endpoint-properties;
} InfoResourceEndpointProperties : ResponseEntityBase;
object-map {
TypedEndpointAddr -> EndpointProps;
} EndpointPropertyMapData;
object {
EndpointPropertyType -> JSONValue;
} EndpointProps;
Specifically, an EndpointPropertyMapData object has one member for
each endpoint indicated in the input parameters (with the name being
the endpoint encoded as a TypedEndpointAddr). The requested
properties for each endpoint are encoded in a corresponding
EndpointProps object, which encodes one name/value pair for each
requested property, where the property names are encoded as strings
of type EndpointPropertyType. An implementation of the protocol in
this document SHOULD assume that the property value is a JSONString and fail to parse if it is not, unless the implementation is using an extension to this document that indicates when and how property values of other data types are signaled. The ALTO server returns the value for each of the requested endpoint properties for each of the endpoints listed in the input parameters. If the ALTO server does not define a requested property's value for a particular endpoint, then it MUST omit that property from the response for only that endpoint.11.4.1.7. Example
POST /endpointprop/lookup HTTP/1.1 Host: alto.example.com Content-Length: 181 Content-Type: application/alto-endpointpropparams+json Accept: application/alto-endpointprop+json,application/alto-error+json { "properties" : [ "my-default-networkmap.pid", "priv:ietf-example-prop" ], "endpoints" : [ "ipv4:192.0.2.34", "ipv4:203.0.113.129" ] } HTTP/1.1 200 OK Content-Length: 396 Content-Type: application/alto-endpointprop+json { "meta" : { "dependent-vtags" : [ {"resource-id": "my-default-network-map", "tag": "7915dc0290c2705481c491a2b4ffbec482b3cf62" } ] }, "endpoint-properties": { "ipv4:192.0.2.34" : { "my-default-network-map.pid": "PID1", "priv:ietf-example-prop": "1" }, "ipv4:203.0.113.129" : { "my-default-network-map.pid": "PID3" } } }
11.5. Endpoint Cost Service
The Endpoint Cost Service provides information about costs between individual endpoints. In particular, this service allows lists of endpoint prefixes (and addresses, as a special case) to be ranked (ordered) by an ALTO server.11.5.1. Endpoint Cost
An endpoint cost resource provides information about costs between individual endpoints. It MAY be provided by an ALTO server. How an ALTO server provides the endpoint cost resource is implementation dependent. An ALTO server may use either fine-grained costs among individual endpoints or coarse-grained costs based on the costs between the PIDs corresponding to the endpoints. See Section 15.3 for additional details.11.5.1.1. Media Type
The media type of the endpoint cost resource is "application/alto- endpointcost+json".11.5.1.2. HTTP Method
The endpoint cost resource is requested using the HTTP POST method.11.5.1.3. Accept Input Parameters
An ALTO client supplies the endpoint cost parameters through a media type "application/alto-endpointcostparams+json", with an HTTP POST entity body of a JSON object of type ReqEndpointCostMap: object { CostType cost-type; [JSONString constraints<0..*>;] EndpointFilter endpoints; } ReqEndpointCostMap; object { [TypedEndpointAddr srcs<0..*>;] [TypedEndpointAddr dsts<0..*>;] } EndpointFilter;
with fields: cost-type: The cost type (Section 10.7) to use for returned costs. The "cost-metric" and "cost-mode" fields MUST match one of the supported cost types indicated in this resource's "capabilities" fields (Section 11.5.1.4). The ALTO client SHOULD omit the "description" field, and if present, the ALTO server MUST ignore the "description" field. constraints: Defined equivalently to the "constraints" input parameter of a filtered cost map (see Section 11.3.2). endpoints: A list of source endpoints and destination endpoints for which path costs are to be returned. If the list of source or destination endpoints is empty (or not included), the ALTO server MUST interpret it as if it contained the endpoint address corresponding to the client IP address from the incoming connection (see Section 13.3 for discussion and considerations regarding this mode). The source and destination endpoint lists MUST NOT be both empty. The ALTO server MUST interpret entries appearing multiple times in a list as if they appeared only once.11.5.1.4. Capabilities
This document defines EndpointCostCapabilities as the same as FilteredCostMapCapabilities. See Section 11.3.2.4.11.5.1.5. Uses
It is important to note that although this resource allows an ALTO server to reveal costs between individual endpoints, the ALTO server is not required to do so. A simple implementation of ECS may compute the cost between two endpoints as the cost between the PIDs corresponding to the endpoints, using one of the exposed network and cost maps defined by the server. ECS MUST NOT specify the "use" field to indicate a network or cost map. Hence, the ECS cost is the cost from the source endpoint to the destination endpoint. A future extension may allow ECS to state that it "uses" a network map. The extension then will need to define the semantics.11.5.1.6. Response
The "meta" field of an endpoint cost response MUST include the "cost- type" field, to indicate the cost type used. The data component of an endpoint cost response is named "endpoint-cost-map", which is a JSON object of type EndpointCostMapData:
object {
EndpointCostMapData endpoint-cost-map;
} InfoResourceEndpointCostMap : ResponseEntityBase;
object-map {
TypedEndpointAddr -> EndpointDstCosts;
} EndpointCostMapData;
object-map {
TypedEndpointAddr -> JSONValue;
} EndpointDstCosts;
Specifically, an EndpointCostMapData object is a dictionary map with
each key representing a TypedEndpointAddr string identifying the
source endpoint specified in the input parameters. For each source
endpoint, an EndpointDstCosts dictionary map object denotes the
associated cost to each destination endpoint specified in input
parameters. An implementation of the protocol in this document
SHOULD assume that the cost value is a JSONNumber and fail to parse
if it is not, unless the implementation is using an extension to this
document that indicates when and how costs of other data types are
signaled. If the ALTO server does not define a cost value from a
source endpoint to a particular destination endpoint, it MAY be
omitted from the response.
11.5.1.7. Example
POST /endpointcost/lookup HTTP/1.1 Host: alto.example.com Content-Length: 248 Content-Type: application/alto-endpointcostparams+json Accept: application/alto-endpointcost+json,application/alto-error+json { "cost-type": {"cost-mode" : "ordinal", "cost-metric" : "routingcost"}, "endpoints" : { "srcs": [ "ipv4:192.0.2.2" ], "dsts": [ "ipv4:192.0.2.89", "ipv4:198.51.100.34", "ipv4:203.0.113.45" ] } } HTTP/1.1 200 OK Content-Length: 274 Content-Type: application/alto-endpointcost+json { "meta" : { "cost-type": {"cost-mode" : "ordinal", "cost-metric" : "routingcost" } }, "endpoint-cost-map" : { "ipv4:192.0.2.2": { "ipv4:192.0.2.89" : 1, "ipv4:198.51.100.34" : 2, "ipv4:203.0.113.45" : 3 } } }
(page 64 continued on part 4)
