tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7285

 
 
 

Application-Layer Traffic Optimization (ALTO) Protocol

Part 3 of 4, p. 38 to 64
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 38 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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 RFC Part