Tech-invite3GPPspaceIETF RFCsSIP
9190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7285

Application-Layer Traffic Optimization (ALTO) Protocol

Pages: 91
Proposed Standard
Errata
Part 2 of 4 – Pages 19 to 38
First   Prev   Next

Top   ToC   RFC7285 - Page 19   prevText

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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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   ToC   RFC7285 - 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 Section