Tech-invite3GPPspaceIETF RFCsSIP
9190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7285

Application-Layer Traffic Optimization (ALTO) Protocol

Pages: 91
Proposed Standard
Errata
Part 3 of 4 – Pages 38 to 64
First   Prev   Next

Top   ToC   RFC7285 - Page 38   prevText

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;
Top   ToC   RFC7285 - Page 39
   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.
Top   ToC   RFC7285 - Page 40
   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].
Top   ToC   RFC7285 - Page 41

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.
Top   ToC   RFC7285 - Page 42

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.
Top   ToC   RFC7285 - Page 43

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.
Top   ToC   RFC7285 - Page 44

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;
Top   ToC   RFC7285 - Page 45
   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" ] } } }
Top   ToC   RFC7285 - Page 46
   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.
Top   ToC   RFC7285 - Page 47
   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.
Top   ToC   RFC7285 - Page 48
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.
Top   ToC   RFC7285 - Page 49
   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.
Top   ToC   RFC7285 - Page 50
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.
Top   ToC   RFC7285 - Page 51
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.
Top   ToC   RFC7285 - Page 52
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.
Top   ToC   RFC7285 - Page 53
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.
Top   ToC   RFC7285 - Page 54
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
Top   ToC   RFC7285 - Page 55
      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.
Top   ToC   RFC7285 - Page 56
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.
Top   ToC   RFC7285 - Page 57
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.
Top   ToC   RFC7285 - Page 58

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:
Top   ToC   RFC7285 - Page 59
       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
Top   ToC   RFC7285 - Page 60
   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" } } }
Top   ToC   RFC7285 - Page 61

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;
Top   ToC   RFC7285 - Page 62
   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:
Top   ToC   RFC7285 - Page 63
       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.
Top   ToC   RFC7285 - Page 64
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)

Next Section