Looking Glass API
draft-mst-lgapi-02
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 8522.
|
|
---|---|---|---|
Author | Markus Stubbig | ||
Last updated | 2015-07-21 | ||
RFC stream | (None) | ||
Formats | |||
IETF conflict review | conflict-review-mst-lgapi, conflict-review-mst-lgapi, conflict-review-mst-lgapi, conflict-review-mst-lgapi, conflict-review-mst-lgapi, conflict-review-mst-lgapi | ||
Additional resources | |||
Stream | Stream state | (No stream defined) | |
Consensus boilerplate | Unknown | ||
RFC Editor Note | (None) | ||
IESG | IESG state | Became RFC 8522 (Informational) | |
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-mst-lgapi-02
Internet-Draft Looking Glass API July 2015 Example response: { "status" : "success", "data" : { "routers" : [ "route-server.lookingglass.example.net", "customer-edge.lookingglass.example.net", "provider-edge.lookingglass.example.net" ], "performed_at" : "2014-10-19T20:07:01Z", "runtime" : 0.73 } } 3.3.2. router details List additional information about the selected router, specified by its router ID. The response MUST contain the routers hostname and router ID. The response MAY contain more details like output format, country code, city, administrative contact, vendor and model. Available output formats are specified by Internet media type as of [RFC6838] and listed in [IANA-MT]. If the routers supports multiple formats, they are separated by comma. The router might provide output formats, that are not yet registered or listed in [IANA-MT]. RFC6838 [RFC6838] provides a tree for unregistered subtypes. For example, output in NETCONF format could use "text/x.netconf". Missing output format defaults to "text/plain", which is a copy of the raw command-line output. Syntax: https://lg.example.net/api/v1/routers/{number} Example query: https://lg.example.net/api/v1/routers/1 Stubbig Expires January 22, 2016 [Page 11] Internet-Draft Looking Glass API July 2015 Example response: { "status" : "success", "data" : { "id" : 1, "name" : "customer-edge.lookingglass.example.net", "format" : "text/plain,text/x.netconf", "country" : "de", "autonomous_system" : 64512 } } 3.3.3. commands This function provides a full list of commands that are available for execution. The list includes mandatory, optional, and additional (Section 3.4) commands. It is equivalent to the "command" HTML drop- down or radio-button form element and contains the same information. The list is formatted as "commands" array containing one object per command. This object contains informative strings about the current command: href, arguments, description and command. Syntax: https://lg.example.net/api/v1/commands Example response: { "status" : "success", "data" : { "commands" : [ { "href" : "https://lg.example.net/api/v1/show/route", "arguments" : "{addr}", "description" : "Print records from IP routing table", "command" : "show route" }, { "href" : "https://lg.example.net/api/v1/traceroute", "arguments" : "{addr}", "description" : "Trace route to destination host", "command" : "traceroute" } ] } } Stubbig Expires January 22, 2016 [Page 12] Internet-Draft Looking Glass API July 2015 3.4. Extensible commands The list of commands MAY be expanded as long as the principles of this document are observed. For example, a Looking Glass provider may not be offering BGP-related commands because of an OSPF-based network. The sample command might be: https://lg.example.net/api/v1/show/ospf/database 4. Miscellaneous The network traffic sent by a "Looking Glass" is not appropriate when measuring Service Level Agreements or validating Quality of Service setting. If a monitoring system uses the Looking Glass API for reachability checks, it SHOULD NOT rely on the HTTP status codes but on the "status" message field inside the HTTP body. 5. IANA Considerations none 6. Security Consideration The use of HTTPS is REQUIRED to ensure a high level of security, privacy, and confidentiality during transit. 6.1. Abuse Potential The main goal of the Looking Glass API is the automated usage of the Looking Glass service. This allows the scripting of API calls, which could be used as a distributed Denial of Service (DDoS) attack. Interestingly, the attacked system recognizes the attack originating from various ISPs core network. It is RECOMMENDED that implementers of the Looking Glass API take steps to mitigate the above described abuse. The strategy can include blocking or rate-limiting by client IP address or target IP network. Stubbig Expires January 22, 2016 [Page 13] Internet-Draft Looking Glass API July 2015 6.2. Authentication Authentication is not a requirement because the current Looking Glass web services are usable without authentication. Requests to the proposed API service MAY be authenticated by any method. The decision is up to the implementers security requirements. 6.3. Minimal information Some of the described commands provide a detailed insight into the providers network. It is therefore up to the implementer's security policy to dismiss commands that are marked as "optional" or restrict commands that are marked as "mandatory". 7. References 7.1. Normative References [IANA-AFN] IANA, "Address Family Numbers", 2015, <https://www.iana.org/assignments/address-family- numbers/>. [IANA-MT] IANA, "Media Types", 2015, <http://www.iana.org/assignments/media-types/ media-types.xhtml>. [IANA-SAFI] IANA, "Subsequent Address Family Identifier (SAFI) Parameters", 2015, <http://www.iana.org/assignments/safi-namespace/>. [JSend] OmniTI Labs, "JSend", 2013, <http://labs.omniti.com/labs/jsend>. [RFC2858] Bates, T., Rekhter, Y., Chandra, R., and D. Katz, "Multiprotocol Extensions for BGP-4", RFC 2858, June 2000. [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. Stubbig Expires January 22, 2016 [Page 14] Internet-Draft Looking Glass API July 2015 7.2. Informative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix Reserved for Documentation", RFC 3849, July 2004. [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks Reserved for Documentation", RFC 5737, January 2010. [RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names", RFC 6761, February 2013. [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, January 2013. [RFC6996] Mitchell, J., "Autonomous System (AS) Reservation for Private Use", BCP 6, RFC 6996, July 2013. [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, July 2014. [iso8601] International Organization for Standardization, "Date and time format--ISO 8601", 2006, <http://www.iso.org/iso/iso8601>. Appendix A. JSend According to [JSend], "JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted. JSend focuses on application-level (as opposed to protocol- or transport-level) messaging which makes it ideal for use in REST-style applications and APIs." A basic JSend-compliant response MUST contain a "status" key and SHOULD contain "data", "message" and "code" keys dependent on the status value. The following table lists the required and optional keys. Stubbig Expires January 22, 2016 [Page 15] Internet-Draft Looking Glass API July 2015 +---------+-----------------+---------------+ | Type | Required keys | Optional keys | +---------+-----------------+---------------+ | success | status, data | | | fail | status, data | | | error | status, message | code, data | +---------+-----------------+---------------+ Table 1: Type and keys in JSend response Author's Address Markus Stubbig Independent Germany Email: stubbig.ietf@gmail.com Stubbig Expires January 22, 2016 [Page 16]