RFC 7285
Application-Layer Traffic Optimization (ALTO) Protocol
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.
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).
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.
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).
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.
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;
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.
+-----------------------+-------------------------------------------+ | 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),
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
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.
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.
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.
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
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.
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" : {
"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".
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:
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" ]
},
"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.
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)
