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 2 of 4, p. 19 to 38
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 19 
8.  Protocol Specification: General Processing

   This section first specifies general client and server processing.
   The details of specific services will be covered in the following
   sections.

8.1.  Overall Design

   The ALTO Protocol uses a REST-ful design.  There are two primary
   components to this design:

   o  Information Resources: Each ALTO service is realized by a set of
      network information resources.  Each information resource has a
      media type [RFC2046].  An ALTO client may construct an HTTP
      request for a particular information resource (including any
      parameters, if necessary), and the ALTO server returns the
      requested information resource in an HTTP response.

Top      Up      ToC       Page 20 
   o  Information Resource Directory (IRD): An ALTO server uses an IRD
      to inform an ALTO client about a list of available information
      resources and the URI at which each can be accessed.  ALTO clients
      consult the IRDs to determine the services provided by ALTO
      servers.

8.2.  Notation

   This document uses JSONString, JSONNumber, and JSONBool to indicate
   the JSON string, number, and boolean types, respectively.  The type
   JSONValue indicates a JSON value, as specified in Section 3 of
   [RFC7159].

   This document uses an adaptation of the C-style struct notation to
   define JSON objects.  A JSON object consists of name/value pairs.
   This document refers to each pair as a field.  In some context, this
   document also refers to a field as an attribute.  The name of a
   field/attribute may be referred to as the key.  An optional field is
   enclosed by [ ].  In the definitions, the JSON names of the fields
   are case sensitive.  An array is indicated by two numbers in angle
   brackets, <m..n>, where m indicates the minimal number of values and
   n is the maximum.  When this document uses * for n, it means no upper
   bound.

   For example, the definition below defines a new type Type4, with
   three fields named "name1", "name2", and "name3", respectively.  The
   field named "name3" is optional, and the field named "name2" is an
   array of at least one value.

    object { Type1 name1; Type2 name2<1..*>; [Type3 name3;]
             } Type4;

   This document also defines dictionary maps (or maps for short) from
   strings to JSON values.  For example, the definition below defines a
   Type3 object as a map.  Type1 must be defined as string, and Type2
   can be defined as any type.

    object-map { Type1 -> Type2; } Type3;

   This document uses subtyping to denote that one type is derived from
   another type.  The example below denotes that TypeDerived is derived
   from TypeBase.  TypeDerived includes all fields defined in TypeBase.
   If TypeBase does not have a field named "name1", TypeDerived will
   have a new field named "name1".  If TypeBase already has a field
   named "name1" but with a different type, TypeDerived will have a
   field named "name1" with the type defined in TypeDerived (i.e., Type1
   in the example).

Top      Up      ToC       Page 21 
    object { Type1 name1; } TypeDerived : TypeBase;

   Note that, despite the notation, no standard, machine-readable
   interface definition or schema is provided in this document.
   Extension documents may describe these as necessary.

8.3.  Basic Operations

   The ALTO Protocol employs standard HTTP [RFC7230].  It is used for
   discovering available information resources at an ALTO server and
   retrieving Information Resources.  ALTO clients and ALTO servers use
   HTTP requests and responses carrying ALTO-specific content with
   encoding as specified in this document, and they MUST be compliant
   with [RFC7230].

   Instead of specifying the generic application/json media type for all
   ALTO request parameters (if any) and responses, ALTO clients and
   servers use multiple, specific JSON-based media types (e.g.,
   application/alto-networkmap+json, application/alto-costmap+json) to
   indicate content types; see Table 2 for a list of media types defined
   in this document.  This allows easy extensibility while maintaining
   clear semantics and versioning.  For example, a new version of a
   component of the ALTO Protocol (e.g., a new version of ALTO network
   maps) can be defined by simply introducing a new media type (e.g.,
   application/alto-networkmap-v2+json).

8.3.1.  Client Discovering Information Resources

   To discover available information resources provided by an ALTO
   server, an ALTO client requests its IRD(s).

   Specifically, using an ALTO service discovery protocol, an ALTO
   client obtains a URI through which it can request an information
   resource directory (IRD).  This document refers to this IRD as the
   Root IRD of the ALTO client.  Each entry in an IRD indicates a URI at
   which an ALTO server accepts requests, and returns either an
   information resource or an information resource directory that
   references additional information resources.  Beginning with its Root
   IRD and following links to IRDs recursively, an ALTO client can
   discover all information resources available to it.  This set of
   information resources is referred to as the information resource
   closure of the ALTO client.  By inspecting its information resource
   closure, an ALTO client can determine whether an ALTO server supports
   the desired information resource, and if it is supported, the URI at
   which it is available.

   See Section 9.2 for a detailed specification of IRDs.

Top      Up      ToC       Page 22 
8.3.2.  Client Requesting Information Resources

   Where possible, the ALTO Protocol uses the HTTP GET method to request
   resources.  However, some ALTO services provide information resources
   that are the function of one or more input parameters.  Input
   parameters are encoded in the HTTP request's entity body, and the
   ALTO client MUST use the HTTP POST method to send the parameters.

   When requesting an ALTO information resource that requires input
   parameters specified in a HTTP POST request, an ALTO client MUST set
   the Content-Type HTTP header to the media type corresponding to the
   format of the supplied input parameters.

   An ALTO client MUST NOT assume that the HTTP GET and POST methods are
   interchangeable.  In particular, for an information resource that
   uses the HTTP GET method, an ALTO client MUST NOT assume that the
   information resource will accept a POST request as equivalent to a
   GET request.

8.3.3.  Server Responding to Information Resource Request

   Upon receiving a request for an information resource that the ALTO
   server can provide, the ALTO server normally returns the requested
   information resource.  In other cases, to be more informative
   ([RFC7231]), the ALTO server either provides the ALTO client with an
   information resource directory indicating how to reach the desired
   information resource, or it returns an ALTO error object; see
   Section 8.5 for more details on ALTO error handling.

   It is possible for an ALTO server to leverage caching HTTP
   intermediaries to respond to both GET and POST requests by including
   explicit freshness information (see Section 14 of [RFC7230]).
   Caching of POST requests is not widely implemented by HTTP
   intermediaries; however, an alternative approach is for an ALTO
   server, in response to POST requests, to return an HTTP 303 status
   code ("See Other") indicating to the ALTO client that the resulting
   information resource is available via a GET request to an alternate
   URL.  HTTP intermediaries that do not support caching of POST
   requests could then cache the response to the GET request from the
   ALTO client following the alternate URL in the 303 response if the
   response to the subsequent GET request contains explicit freshness
   information.

   The ALTO server MUST indicate the type of its response using a media
   type (i.e., the Content-Type HTTP header of the response).

Top      Up      ToC       Page 23 
8.3.4.  Client Handling Server Response

8.3.4.1.  Using Information Resources

   This specification does not indicate any required actions taken by
   ALTO clients upon successfully receiving an information resource from
   an ALTO server.  Although ALTO clients are suggested to interpret the
   received ALTO information and adapt application behavior, ALTO
   clients are not required to do so.

8.3.4.2.  Handling Server Response and IRD

   After receiving an information resource directory, the client can
   consult it to determine if any of the offered URIs contain the
   desired information resource.  However, an ALTO client MUST NOT
   assume that the media type returned by the ALTO server for a request
   to a URI is the media type advertised in the IRD or specified in its
   request (i.e., the client must still check the Content-Type header).
   The expectation is that the media type returned should normally be
   the media type advertised and requested, but, in some cases, it may
   legitimately not be so.

   In particular, it is possible for an ALTO client to receive an
   information resource directory from an ALTO server as a response to
   its request for a specific information resource.  In this case, the
   ALTO client may ignore the response or still parse the response.  To
   indicate that an ALTO client will always check if a response is an
   information resource directory, the ALTO client can indicate in the
   "Accept" header of a HTTP request that it can accept information
   resource directory; see Section 9.2.1 for the media type.

8.3.4.3.  Handling Error Conditions

   If an ALTO client does not successfully receive a desired information
   resource from a particular ALTO server (i.e., server response
   indicates error or there is no response), the client can either
   choose another server (if one is available) or fall back to a default
   behavior (e.g., perform peer selection without the use of ALTO
   information, when used in a peer-to-peer system).

8.3.5.  Authentication and Encryption

   ALTO server implementations as well as ALTO client implementations
   MUST support the "https" URI scheme [RFC2818] and Transport Layer
   Security (TLS) [RFC5246].  See Section 15.1.2 for security
   considerations and Section 16 for manageability considerations
   regarding the usage of HTTPS/TLS.

Top      Up      ToC       Page 24 
   For deployment scenarios where client authentication is desired, HTTP
   Digest Authentication MUST be supported.  TLS Client Authentication
   is the preferred mechanism if it is available.

8.3.6.  Information Refreshing

   An ALTO client can determine the frequency at which ALTO information
   is refreshed based on information made available via HTTP.

8.3.7.  Parsing of Unknown Fields

   This document only details object fields used by this specification.
   Extensions may include additional fields within JSON objects defined
   in this document.  ALTO implementations MUST ignore unknown fields
   when processing ALTO messages.

8.4.  Server Response Encoding

   Though each type of ALTO server response (i.e., an information
   resource directory, an individual information resource, or an error
   message) has its distinct syntax and, hence, its unique media type,
   they are designed to have a similar structure: a field named "meta"
   to provide meta definitions, and another field named "data" to
   contain the data, if needed.

   Specifically, this document defines the base type of each ALTO server
   response as ResponseEntityBase:

    object { ResponseMeta meta; } ResponseEntityBase;

   with field:

   meta:  meta information pertaining to the response.

8.4.1.  Meta Information

   Meta information is encoded as a map object for flexibility.
   Specifically, ResponseMeta is defined as:

    object-map { JSONString -> JSONValue } ResponseMeta;

Top      Up      ToC       Page 25 
8.4.2.  Data Information

   The data component of the response encodes the response-specific
   data.  This document derives five types from ResponseEntityBase to
   add different types of data component: InfoResourceDirectory
   (Section 9.2.2), InfoResourceNetworkMap (Section 11.2.1.6),
   InfoResourceCostMap (Section 11.2.3.6),
   InfoResourceEndpointProperties (Section 11.4.1.6), and
   InfoResourceEndpointCostMap (Section 11.5.1.6).

8.5.  Protocol Errors

   If an ALTO server encounters an error while processing a request, the
   ALTO server SHOULD return additional ALTO-layer information, if it is
   available, in the form of an ALTO error resource encoded in the HTTP
   response' entity body.  If no ALTO-layer information is available, an
   ALTO server may omit the ALTO error resource from the response.

   With or without additional ALTO-layer error information, an ALTO
   server MUST set an appropriate HTTP status code.  It is important to
   note that the HTTP status code and ALTO error resource have distinct
   roles.  An ALTO error resource provides detailed information about
   why a particular request for an ALTO information resource was not
   successful.  The HTTP status code, on the other hand, indicates to
   HTTP processing elements (e.g., intermediaries and clients) how the
   response should be treated.

8.5.1.  Media Type

   The media type for an ALTO error response is "application/
   alto-error+json".

8.5.2.  Response Format and Error Codes

   An ALTO error response MUST include a field named "code" in the
   "meta" field of the response.  The value MUST be an ALTO error code,
   encoded in string, defined in Table 1.  Note that the ALTO error
   codes defined in Table 1 are limited to support the error conditions
   needed for purposes of this document.  Additional status codes may be
   defined in companion or extension documents.

Top      Up      ToC       Page 26 
   +-----------------------+-------------------------------------------+
   | ALTO Error Code       | Description                               |
   +-----------------------+-------------------------------------------+
   | E_SYNTAX              | Parsing error in request (including       |
   |                       | identifiers)                              |
   | E_MISSING_FIELD       | A required JSON field is missing          |
   | E_INVALID_FIELD_TYPE  | The type of the value of a JSON field is  |
   |                       | invalid                                   |
   | E_INVALID_FIELD_VALUE | The value of a JSON field is invalid      |
   +-----------------------+-------------------------------------------+

                     Table 1: Defined ALTO Error Codes

   After an ALTO server receives a request, it needs to verify the
   syntactic and semantic validity of the request.  The following
   paragraphs in this section are intended to illustrate the usage of
   the error codes defined above during the verification.  An individual
   implementation may define its message processing in a different
   order.

   In the first step after an ALTO server receives a request, it checks
   the syntax of the request body (i.e., whether the JSON structure can
   be parsed), and indicates a syntax error using the error code
   E_SYNTAX.  For an E_SYNTAX error, the ALTO server MAY provide an
   optional field named "syntax-error" in the "meta" field of the error
   response.  The objective of providing "syntax-error" is to provide
   technical debugging information to developers, not end users.  Hence,
   it should be a human-readable, free-form text describing the syntax
   error.  If possible, the text should include position information
   about the syntax error, such as line number and offset within the
   line.  If nothing else, the value of the field named "syntax-error"
   could include just the position.  If a syntax error occurs in a
   production environment, the ALTO client could inform the end user
   that there was an error communicating with the ALTO server, and
   suggest that the user submit the error information, which includes
   "syntax-error", to the developers.

   A request without syntax errors may still be invalid.  An error case
   is that the request misses a required field.  The server indicates
   such an error using the error code E_MISSING_FIELD.  This document
   defines required fields for Filtered Network Map (Section 11.3.1.3),

Top      Up      ToC       Page 27 
   Filtered Cost Map (Section 11.3.2.3), Endpoint Properties
   (Section 11.4.1.3), and Endpoint Cost (Section 11.5.1.3) services.
   For an E_MISSING_FIELD error, the server may include an optional
   field named "field" in the "meta" field of the error response, to
   indicate the missing field. "field" should be a JSONString indicating
   the full path of the missing field.  For example, assume that a
   Filtered Cost Map request (see Section 11.3.2.3) omits the "cost-
   metric" field.  The error response from the ALTO server may specify
   the value of "field" as "cost-type/cost-metric".

   A request with the correct fields might use a wrong type for the
   value of a field.  For example, the value of a field could be a
   JSONString when a JSONNumber is expected.  The server indicates such
   an error using the error code E_INVALID_FIELD_TYPE.  The server may
   include an optional field named "field" in the "meta" field of the
   response, to indicate the field that contains the wrong type.

   A request with the correct fields and types of values for the fields
   may specify a wrong value for a field.  For example, a Filtered Cost
   Map request may specify a wrong value for CostMode in the "cost-type"
   field (Section 11.3.2.3).  The server indicates such an error with
   the error code E_INVALID_FIELD_VALUE.  For an E_INVALID_FIELD_VALUE
   error, the server may include an optional field named "field" in the
   "meta" field of the response, to indicate the field that contains the
   wrong value.  The server may also include an optional field named
   "value" in the "meta" field of the response to indicate the wrong
   value that triggered the error.  If the "value" field is specified,
   the "field" field MUST be specified.  The "value" field MUST have a
   JSONString value.  If the invalid value is not a string, the ALTO
   server MUST convert it to a string.  Below are the rules to specify
   the "value" key:

   o  If the invalid value is a string, "value" is that string;

   o  If the invalid value is a number, "value" must be the invalid
      number as a string;

   o  If the invalid value is a subfield, the server must set the
      "field" key to the full path of the field name and "value" to the
      invalid subfield value, converting it to a string if needed.  For
      example, if the "cost-mode" subfield of the "cost-type" field is
      an invalid mode "foo", the server should set "value" to "foo", and
      "field" to "cost-mode/cost-type";

   o  If an element of a JSON array has an invalid value, the server
      sets "value" to the value of the invalid element, as a string, and
      "field" to the name of the array.  An array element of the wrong
      type (e.g., a number in what is supposed to be an array of

Top      Up      ToC       Page 28 
      strings) is an invalid value error, not an invalid type error.
      The server sets "value" to the string version of the incorrect
      element, and "field" to the name of the array.

   If multiple errors are present in a single request (e.g., a request
   uses a JSONString when a JSONNumber is expected and a required field
   is missing), then the ALTO server MUST return exactly one of the
   detected errors.  However, the reported error is implementation
   defined, since specifying a particular order for message processing
   encroaches needlessly on implementation techniques.

8.5.3.  Overload Conditions and Server Unavailability

   If an ALTO server detects that it cannot handle a request from an
   ALTO client due to excessive load, technical problems, or system
   maintenance, it SHOULD do one of the following:

   o  Return an HTTP 503 ("Service Unavailable") status code to the ALTO
      client.  As indicated by [RFC7230], the Retry-After HTTP header
      may be used to indicate when the ALTO client should retry the
      request.

   o  Return an HTTP 307 ("Temporary Redirect") status code indicating
      an alternate ALTO server that may be able to satisfy the request.
      Using Temporary Redirect may generate infinite redirection loops.
      Although [RFC7231] Section 6.4 specifies that an HTTP client
      SHOULD detect infinite redirection loops, it is more desirable
      that multiple ALTO servers be configured not to form redirection
      loops.

   The ALTO server MAY also terminate the connection with the ALTO
   client.

   The particular policy applied by an ALTO server to determine that it
   cannot service a request is outside of the scope of this document.

9.  Protocol Specification: Information Resource Directory

   As already discussed, an ALTO client starts by retrieving an
   information resource directory, which specifies the attributes of
   individual information resources that an ALTO server provides.

Top      Up      ToC       Page 29 
9.1.  Information Resource Attributes

   In this document, each information resource has up to five attributes
   associated with it, including its assigned ID, its response format,
   its capabilities, its accepted input parameters, and other resources
   on which it may depend.  The function of an information resource
   directory is to publishes these attributes.

9.1.1.  Resource ID

   Each information resource that an ALTO client can request MUST be
   assigned a resource ID attribute that is unique amongst all
   information resources in the information resource closure of the
   client.  The resource ID SHOULD remain stable even when the data
   provided by that resource changes.  For example, even though the
   number of PIDs in an ALTO network map may be adjusted, its resource
   ID should remain the same.  Similarly, if the entries in an ALTO cost
   map are updated, its resource ID should remain the same.  IDs SHOULD
   NOT be reused for different resources over time.

9.1.2.  Media Type

   ALTO uses media types [RFC2046] to uniquely indicate the data format
   used to encode the content to be transmitted between an ALTO server
   and an ALTO client in the HTTP entity body.

9.1.3.  Capabilities

   The Capabilities attribute of an information resource indicates
   specific capabilities that the server can provide.  For example, if
   an ALTO server allows an ALTO client to specify cost constraints when
   the client requests a cost map information resource, then the server
   advertises the "cost-constraints" capability of the cost map
   information resource.

9.1.4.  Accepts Input Parameters

   An ALTO server may allow an ALTO client to supply input parameters
   when requesting certain information resources.  The associated
   "accepts" attribute of such an information resource specifies a media
   type, which indicates how the client specifies the input parameters
   as contained in the entity body of the HTTP POST request.

Top      Up      ToC       Page 30 
9.1.5.  Dependent Resources

   The information provided in an information resource may use
   information provided in some other resources (e.g., a cost map uses
   the PIDs defined in a network map).  The "uses" attribute conveys
   such information.

9.2.  Information Resource Directory (IRD)

   An ALTO server uses the information resource directory to publish
   available information resources and their aforementioned attributes.
   Since resource selection happens after consumption of the information
   resource directory, the format of the information resource directory
   is designed to be simple with the intention of future ALTO Protocol
   versions maintaining backwards compatibility.  Future extensions or
   versions of the ALTO Protocol SHOULD be accomplished by extending
   existing media types or adding new media types but retaining the same
   format for the Information Resource Directory.

   An ALTO server MUST make one information resource directory available
   via the HTTP GET method to a URI discoverable by an ALTO client.
   Discovery of this URI is out of scope of this document, but it could
   be accomplished by manual configuration or by returning the URI of an
   information resource directory from the ALTO Discovery Protocol
   [ALTO-SERVER-DISC].  For recommendations on what the URI may look
   like, see [ALTO-SERVER-DISC].

9.2.1.  Media Type

   The media type to indicate an information resource directory is
   "application/alto-directory+json".

9.2.2.  Encoding

   An information resource directory response may include in the "meta"
   field the "cost-types" field, whose value is of type IRDMetaCostTypes
   defined below, where CostType is defined in Section 10.7:


       object-map {
         JSONString -> CostType;
       } IRDMetaCostTypes;


   The function of "cost-types" is to assign names to a set of CostTypes
   that can be used in one or more "resources" entries in the IRD to
   simplify specification.  The names defined in "cost-types" in an IRD
   are local to the IRD.

Top      Up      ToC       Page 31 
   For a Root IRD, "meta" MUST include a field named "default-alto-
   network-map", which value specifies the resource ID of an ALTO
   network map.  When there are multiple network maps defined in an IRD
   (e.g., with different levels of granularity), the "default-alto-
   network-map" field provides a guideline to simple clients that use
   only one network map.

   The data component of an information resource directory response is
   named "resources", which is a JSON object of type IRDResourceEntries:

       object {
         IRDResourceEntries resources;
       } InfoResourceDirectory : ResponseEntityBase;


       object-map {
         ResourceID  -> IRDResourceEntry;
       } IRDResourceEntries;

       object {
         JSONString      uri;
         JSONString      media-type;
         [JSONString     accepts;]
         [Capabilities   capabilities;]
         [ResourceID     uses<0..*>;]
       } IRDResourceEntry;



       object {
         ...
       } Capabilities;

   An IRDResourceEntries object is a dictionary map keyed by
   ResourceIDs, where ResourceID is defined in Section 10.2.  The value
   of each entry specifies:

   uri:           A URI at which the ALTO server provides one or more
                  information resources, or an information resource
                  directory indicating additional information resources.
                  URIs can be relative to the URI of the IRD and MUST be
                  resolved according to Section 5 of [RFC3986].

   media-type:    The media type of the information resource (see
                  Section 9.1.2) available via GET or POST requests to
                  the corresponding URI.  A value of "application/
                  alto-directory+json" indicates that the response for a

Top      Up      ToC       Page 32 
                  request to the URI will be an information resource
                  directory defining additional information resources in
                  the information resource closure.

   accepts:       The media type of input parameters (see Section 9.1.4)
                  accepted by POST requests to the corresponding URI.
                  If this field is not present, it MUST be assumed to be
                  empty.

   capabilities:  A JSON object enumerating capabilities of an ALTO
                  server in providing the information resource at the
                  corresponding URI and information resources
                  discoverable via the URI.  If this field is not
                  present, it MUST be assumed to be an empty object.  If
                  a capability for one of the offered information
                  resources is not explicitly listed here, an ALTO
                  client may either issue an OPTIONS HTTP request to the
                  corresponding URI to determine if the capability is
                  supported or assume its default value documented in
                  this specification or an extension document describing
                  the capability.

   uses:          A list of resource IDs, defined in the same IRD, that
                  define the resources on which this resource directly
                  depends.  An ALTO server SHOULD include in this list
                  any resources that the ALTO client would need to
                  retrieve in order to interpret the contents of this
                  resource.  For example, an ALTO cost map resource
                  should include in this list the network map on which
                  it depends.  ALTO clients may wish to consult this
                  list in order to pre-fetch necessary resources.

   If an entry has an empty list for "accepts", then the corresponding
   URI MUST support GET requests.  If an entry has a non-empty
   "accepts", then the corresponding URI MUST support POST requests.  If
   an ALTO server wishes to support both GET and POST on a single URI,
   it MUST specify two entries in the information resource directory.

9.2.3.  Example

   The following is an example information resource directory returned
   by an ALTO server to an ALTO client.  Assume it is the Root IRD of
   the client.

Top      Up      ToC       Page 33 
     GET /directory HTTP/1.1
     Host: alto.example.com
     Accept: application/alto-directory+json,application/alto-error+json

      HTTP/1.1 200 OK
      Content-Length: 2333
      Content-Type: application/alto-directory+json

      {
        "meta" : {
           "cost-types": {
              "num-routing": {
                 "cost-mode"  : "numerical",
                 "cost-metric": "routingcost",
                 "description": "My default"
              },
              "num-hop":     {
                 "cost-mode"  : "numerical",
                 "cost-metric": "hopcount"
              },
              "ord-routing": {
                 "cost-mode"  : "ordinal",
                 "cost-metric": "routingcost"
              },
              "ord-hop":     {
                 "cost-mode"  : "ordinal",
                 "cost-metric": "hopcount"
              }
           },
           "default-alto-network-map" : "my-default-network-map"
        },
        "resources" : {
           "my-default-network-map" : {
              "uri" : "http://alto.example.com/networkmap",
              "media-type" : "application/alto-networkmap+json"
           },
           "numerical-routing-cost-map" : {
              "uri" : "http://alto.example.com/costmap/num/routingcost",
              "media-type" : "application/alto-costmap+json",
              "capabilities" : {
                 "cost-type-names" : [ "num-routing" ]
              },
              "uses": [ "my-default-network-map" ]
           },
           "numerical-hopcount-cost-map" : {
              "uri" : "http://alto.example.com/costmap/num/hopcount",
              "media-type" : "application/alto-costmap+json",
              "capabilities" : {

Top      Up      ToC       Page 34 
                 "cost-type-names" : [ "num-hop" ]
              },
              "uses": [ "my-default-network-map" ]
           },
           "custom-maps-resources" : {
              "uri" : "http://custom.alto.example.com/maps",
              "media-type" : "application/alto-directory+json"
           },
           "endpoint-property" : {
              "uri" : "http://alto.example.com/endpointprop/lookup",
              "media-type" : "application/alto-endpointprop+json",
              "accepts" : "application/alto-endpointpropparams+json",
              "capabilities" : {
                "prop-types" : [ "my-default-network-map.pid",
                                 "priv:ietf-example-prop" ]
              },
           },
           "endpoint-cost" : {
              "uri" : "http://alto.example.com/endpointcost/lookup",
              "media-type" : "application/alto-endpointcost+json",
              "accepts" : "application/alto-endpointcostparams+json",
              "capabilities" : {
                 "cost-constraints" : true,
                 "cost-type-names" : [ "num-routing", "num-hop",
                                       "ord-routing", "ord-hop"]
              }
           }
        }
      }


   Specifically, the "cost-types" field of "meta" of the example IRD
   defines names for four cost types in this IRD.  For example,
   "num-routing" in the example is the name that refers to a cost type
   with cost mode being "numerical" and cost metric being "routingcost".
   This name is used in the second entry of "resources", which defines a
   cost map.  In particular, the "cost-type-names" of its "capabilities"
   specifies that this resource supports a cost type named as
   "num-routing".  The ALTO client looks up the name "num-routing" in
   "cost-types" of the IRD to obtain the cost type named as
   "num-routing".  The last entry of "resources" uses all four names
   defined in "cost-types".

   Another field defined in "meta" of the example IRD is
   "default-alto-network-map", which has value "my-default-network-map",
   which is the resource ID of an ALTO network map that will be defined
   in "resources".

Top      Up      ToC       Page 35 
   The "resources" field of the example IRD defines six information
   resources.  For example, the second entry, which is assigned a
   resource ID "numerical-routing-cost-map", provides a cost map, as
   indicated by the media-type "application/alto-costmap+json".  The
   cost map is based on the network map defined with resource ID
   "my-default-network-map".  As another example, the last entry, which
   is assigned resource ID "endpoint-cost", provides the Endpoint Cost
   Service, which is indicated by the media-type "application/
   alto-endpointcost+json".  An ALTO client should use uri
   "http://alto.example.com/endpointcost/lookup" to access the service.

   The ALTO client should format its request body to be the
   "application/alto-endpointcostparams+json" media type, as specified
   by the "accepts" attribute of the information resource.  The "cost-
   type-names" field of the "capabilities" attribute of the information
   resource includes four defined cost types specified in the "cost-
   types" field of "meta" of the IRD.  Hence, an ALTO client can verify
   that the Endpoint Cost information resource supports both cost
   metrics "routingcost" and "hopcount", each available for both
   "numerical" and "ordinal" cost modes.  When requesting the
   information resource, an ALTO client can specify cost constraints, as
   indicated by the "cost-constraints" field of the "capabilities"
   attribute.

9.2.4.  Delegation Using IRD

   ALTO IRDs provide the flexibility to define a set of information
   resources that are provided by ALTO servers running in multiple
   domains.  Consider the preceding example.  Assume that the ALTO
   server running at alto.example.com wants to delegate some information
   resources to a separate subdomain: "custom.alto.example.com".  In
   particular, assume that the maps available via this subdomain are
   filtered network maps, filtered cost maps, and some pre-generated
   maps for the "hopcount" and "routingcost" cost metrics in the
   "ordinal" cost mode.  The fourth entry of "resources" in the
   preceding example IRD implements the delegation.  The entry has a
   media-type of "application/alto-directory+json", and an ALTO client
   can discover the information resources available at
   "custom.alto.example.com" if its request to
   "http://custom.alto.example.com/maps" is successful:

Top      Up      ToC       Page 36 
     GET /maps HTTP/1.1
     Host: custom.alto.example.com
     Accept: application/alto-directory+json,application/alto-error+json

   HTTP/1.1 200 OK
   Content-Length: 1900
   Content-Type: application/alto-directory+json

   {
     "meta" : {
        "cost-types": {
           "num-routing": {
              "cost-mode"  : "numerical",
              "cost-metric": "routingcost",
              "description": "My default"
           },
           "num-hop":     {
              "cost-mode"  : "numerical",
              "cost-metric": "hopcount"
           },
           "ord-routing": {
              "cost-mode"  : "ordinal",
              "cost-metric": "routingcost"
           },
           "ord-hop":     {
              "cost-mode"  : "ordinal",
              "cost-metric": "hopcount"
           }
        }
     },
     "resources" : {
        "filtered-network-map" : {
           "uri" : "http://custom.alto.example.com/networkmap/filtered",
           "media-type" : "application/alto-networkmap+json",
           "accepts" : "application/alto-networkmapfilter+json",
           "uses": [ "my-default-network-map" ]
        },
        "filtered-cost-map" : {
           "uri" : "http://custom.alto.example.com/costmap/filtered",
           "media-type" : "application/alto-costmap+json",
           "accepts" : "application/alto-costmapfilter+json",
           "capabilities" : {
              "cost-constraints" : true,
              "cost-type-names"  : [ "num-routing", "num-hop",
                                     "ord-routing", "ord-hop" ]
           },
           "uses": [ "my-default-network-map" ]
        },

Top      Up      ToC       Page 37 
        "ordinal-routing-cost-map" : {
           "uri" : "http://custom.alto.example.com/ord/routingcost",
           "media-type" : "application/alto-costmap+json",
           "capabilities" : {
              "cost-type-names" : [ "ord-routing" ]
           },
           "uses": [ "my-default-network-map" ]
        },
        "ordinal-hopcount-cost-map" : {
           "uri" : "http://custom.alto.example.com/ord/hopcount",
           "media-type" : "application/alto-costmap+json",
           "capabilities" : {
              "cost-type-names" : [ "ord-hop" ]
           },
           "uses": [ "my-default-network-map" ]
        }
     }
   }

   Note that the subdomain does not define any network maps, and uses
   the network map with resource ID "my-default-network-map" defined in
   the Root IRD.

9.2.5.  Considerations of Using IRD

9.2.5.1.  ALTO client

   This document specifies no requirements or constraints on ALTO
   clients with regard to how they process an information resource
   directory to identify the URI corresponding to a desired information
   resource.  However, some advice is provided for implementers.

   It is possible that multiple entries in the directory match a desired
   information resource.  For instance, in the example in Section 9.2.3,
   a full cost map with the "numerical" cost mode and the "routingcost"
   cost metric could be retrieved via a GET request to
   "http://alto.example.com/costmap/num/routingcost" or via a POST
   request to "http://custom.alto.example.com/costmap/filtered".

   In general, it is preferred for ALTO clients to use GET requests
   where appropriate, since it is more likely for responses to be
   cacheable.  However, an ALTO client may need to use POST, for
   example, to get ALTO costs or properties that are for a restricted
   set of PIDs or endpoints or to update cached information previously
   acquired via GET requests.

Top      Up      ToC       Page 38 
9.2.5.2.  ALTO server

   This document indicates that an ALTO server may or may not provide
   the information resources specified in the Map-Filtering Service.  If
   these resources are not provided, it is indicated to an ALTO client
   by the absence of a network map or cost map with any media types
   listed under "accepts".



(page 38 continued on part 3)

Next RFC Part