Skip to main content

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]