idnits 2.17.1
draft-mst-lgapi-11.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (November 19, 2018) is 1957 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615)
** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110)
-- Obsolete informational reference (is this intentional?): RFC 7320
(Obsoleted by RFC 8820)
Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Stubbig
3 Internet-Draft Independent
4 Intended status: Informational November 19, 2018
5 Expires: May 23, 2019
7 Looking Glass command set
8 draft-mst-lgapi-11
10 Abstract
12 This document introduces a command set standard to the web-based
13 "Network Looking Glass" software. Its purpose is to provide
14 application programmers uniform access to the Looking Glass service
15 and to analyze standardized response.
17 The interface is supposed to provide the same level of information as
18 web-based interfaces, but in a computer-readable format.
20 Status of This Memo
22 This Internet-Draft is submitted in full conformance with the
23 provisions of BCP 78 and BCP 79.
25 Internet-Drafts are working documents of the Internet Engineering
26 Task Force (IETF). Note that other groups may also distribute
27 working documents as Internet-Drafts. The list of current Internet-
28 Drafts is at https://datatracker.ietf.org/drafts/current/.
30 Internet-Drafts are draft documents valid for a maximum of six months
31 and may be updated, replaced, or obsoleted by other documents at any
32 time. It is inappropriate to use Internet-Drafts as reference
33 material or to cite them other than as "work in progress."
35 This Internet-Draft will expire on May 23, 2019.
37 Copyright Notice
39 Copyright (c) 2018 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (https://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
52 Table of Contents
54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
55 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3
56 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 3
57 1.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 3
58 2. Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
59 2.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 4
60 2.2. Query Parameters . . . . . . . . . . . . . . . . . . . . 4
61 2.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6
62 3. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 8
63 3.1. Diagnostic commands . . . . . . . . . . . . . . . . . . . 8
64 3.2. Informational commands . . . . . . . . . . . . . . . . . 10
65 3.3. Organizational commands . . . . . . . . . . . . . . . . . 14
66 3.4. Extensible commands . . . . . . . . . . . . . . . . . . . 16
67 4. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 16
68 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
69 5.1. Well-Known URIs Registry . . . . . . . . . . . . . . . . 17
70 6. Security Consideration . . . . . . . . . . . . . . . . . . . 17
71 6.1. Abuse Potential . . . . . . . . . . . . . . . . . . . . . 17
72 6.2. Authentication . . . . . . . . . . . . . . . . . . . . . 17
73 6.3. Minimal information . . . . . . . . . . . . . . . . . . . 17
74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
75 7.1. Normative References . . . . . . . . . . . . . . . . . . 18
76 7.2. Informative References . . . . . . . . . . . . . . . . . 19
77 Appendix A. JSend . . . . . . . . . . . . . . . . . . . . . . . 19
78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
80 1. Introduction
82 Many Internet service providers (ISPs) and Internet exchange points
83 (IXPs) offer a complimentary web-based service to their customers and
84 the general public that gives insights to the backbone routing table,
85 BGP neighbor information, or offered routes. This service is known
86 as a "Network Looking Glass". Because they utilize a web-based
87 interface, it is hard to automate access to the services and make
88 that automation transferable between different service
89 implementations.
91 This document describes a common command set to provide application
92 programmers uniform access to Looking Glass services.
94 The commands are intended to provide the same level of information as
95 available via web-based interfaces, but to do so in a computer-
96 readable format. The intention is that multiple implementers of
97 Looking Glass services can provide access through these commands so
98 that an application can make use of the different implementations.
100 The command set is split into mandatory-to-support, optional, and
101 additional. The commands are extensible for new features and for
102 value-add by implementations.
104 The Looking Glass command set is described as a language-independent
105 concept. Consequently, any programming language, which satisfies the
106 commands listed in the following chapters, is acceptable.
108 This work is not the output of the IETF and is presented in the hope
109 that Looking Glass implementers will offer a common programmable
110 interface.
112 1.1. Background
114 The requirement of a uniform access to a Looking Glass service
115 becomes important when multiple Looking Glasses are part of a
116 monitoring system. Implementing a web client and HTTP-parser for
117 every kind of web-based Looking Glass is a time-consuming workaround.
118 However, the Looking Glass command set is a much more viable,
119 compatible, and scalable solution.
121 1.2. Syntax Notation
123 This specification uses the JavaScript Object Notation (JSON) of
124 [RFC8259] arranged as JSend (Appendix A) compliant responses.
126 1.3. Examples
128 All URLs in this documentation use the reserved sample domain of
129 "example.net" as defined in [RFC6761] section 6.5.
131 The URLs further use the fixed [RFC5785] prefix of ".well-known/
132 looking-glass" to prevent a collision in the domains namespace.
134 IPv4 addresses use the documenation block of 192.0.2.0/24 [RFC5737]
135 and IPv6 addresses reside in the reserved prefix of 2001:DB8::/32
136 [RFC3849]. BGP Autonomous System numbers are chosen from the private
137 AS range defined in [RFC6996].
139 The examples skip some required parameters for reasons of simplicity.
141 2. Operation
143 A client issues a query using the HTTP GET method to request specific
144 resources from the server. The resource is a URI and can be
145 informational or a command execution. The client must present all
146 necessary parameters for the server to execute the command on the
147 selected router. Every call is stateless and independent of the
148 previous one.
150 The path component of the resource URI must use the prefix of ".well-
151 known/looking-glass" (see Section 5.1) to stay namespace neutral.
153 The "call" is a request from the client, which specifies a pre-
154 defined operation ("function") that the server will execute on a
155 selected router. The "command" is a task executed on the router and
156 initiated by the server on behalf of the client. The type and scope
157 of all commands are defined and limited by the server. The client
158 must not be able to execute random commands on the targeting router.
159 There must not be any direct communication between the client and the
160 router.
162 After the execution of the command on the selected router has
163 finished, the server replies to the client if the operation has
164 either succeeded, failed or timed out. The response is sent to the
165 client in JSON format. The communication protocol used between the
166 server and router is not specified by this document; any method (e.g.
167 Telnet, SSH, NETCONF, serial console) is acceptable.
169 All parameters and its values are case-insensitive.
171 2.1. Method Parameters
173 Method parameters are mandatory components of the URI and placed in
174 the "path" section in terms of [RFC7320]. Basically, the method
175 parameters specify the call and determine which command the client
176 wants to be executed on the selected router.
178 2.2. Query Parameters
180 Query parameters are optional components of the URI and placed in the
181 "query" section in terms of [RFC7320]. Generally, the query
182 parameters are additional instructions for the requested command.
184 protocol
185 Restrict the command and method parameters to use the specified
186 protocol and version. Protocol is selected as "Address Family
187 Identifier" [IANA-AFN] [RFC4760] and optional "Subsequent Address
188 Family Identifier" [IANA-SAFI] separated by comma.
190 Default value is 1,1 (IP version 4, unicast).
191 JSON datatype is String.
192 Examples:
194 * protocol=2,1 (IP version 6, unicast)
196 * protocol=26 (MPLS, no SAFI used)
198 router
199 Run the command on the router identified by its name. This is not
200 necessarily the router's hostname as long as the Looking Glass
201 software recognizes it.
202 Default value is the first router in the list of available
203 routers.
204 JSON datatype is String.
205 Example: router=rbgn06.example.net
207 routerindex
208 Run the command on this router identified by its position in the
209 list of available routers.
210 Default value is "0".
211 JSON datatype is Number.
212 Example: routerindex=8
214 random
215 Append a random string to prevent the client (or an intermediate
216 proxy) from caching the response. The server must ignore its
217 value.
218 No default value.
219 JSON datatype is String.
220 Example: random=517A93B50
222 vrf
223 Run the command from the selected routing table. This parameter
224 is valid only on routers that support "Virtual Routing and
225 Forwarding" (VRF).
226 No default value.
227 JSON datatype is String.
228 Example: vrf=mgmt
230 runtime
231 Stop executing the command after the runtime limit (in seconds) is
232 exceeded. A value of 0 disables the limit.
233 Default value is "30".
234 JSON datatype is Number.
235 Example: runtime=60
237 format
238 Request the server to provide the output (if any) in the selected
239 format. Specify multiple formats separated by comma in descending
240 order of preference. See Section 3.3.2 for more details.
241 Default value is "text/plain" (raw/unformatted output).
242 JSON datatype is String.
243 Example: format=application/yang,text/plain
245 2.3. Response
247 The HTTP response header contains an appropriate HTTP status code as
248 defined in [RFC7231] with the Content-Type set to "application/json".
250 The HTTP body contains details and error descriptions. The response
251 text must comply with the JSON syntax specification JSend, which is
252 briefly explained in Appendix A. Consequently every response must
253 contain a "status" field of either "success", "fail", or "error",
254 that are explained in the following sections.
256 2.3.1. Success
258 A successful response must set the "status" field to "success". It
259 must also contain a "data" object including the following
260 information:
262 performed_at
263 combined date and time in UTC ISO 8601 [iso8601] indicating when
264 the operation finished. This information must be present.
266 runtime
267 amount of seconds (wallclock) used to run the command. This
268 information must be present.
270 router
271 the name of the router, that executed the command. This
272 information may be present.
274 output
275 output of the command in a format that was requested by the client
276 or defaults to raw output as it appeared on the router's command
277 line interface (CLI). It might even be blank if the command did
278 not produce any output. This information should be present.
280 format
281 selected output format by the server. The client might request
282 multiple formats, so that the "Looking Glass" server has to choose
283 the best option and tell the client which format was selected.
284 This information should be present (or defaults to "text/plain" if
285 missing).
287 Adding more information to the response is permitted and must be
288 placed inside the "data" object.
290 The HTTP status code should be 200.
292 Example:
294 HTTP/1.1 200 OK
295 Content-Type: application/json
296 {
297 "status" : "success",
298 "data" : {
299 "router" : "route-server.lookingglass.example.net"
300 "performed_at" : "2014-10-15T17:15:34Z",
301 "runtime" : 2.63,
302 "output" : [
303 "full raw output from the observing router..."
304 ],
305 "format" : "text/plain"
306 }
307 }
309 2.3.2. Fail
311 A status of "fail" indicates that the selected command was executed
312 on the router but failed to succeed. The response message must set
313 the "status" field to "fail" and must contain the "data" object with
314 command-specific content, that is listed in Section 2.3.1.
316 The HTTP status code should be 200.
318 Example:
320 HTTP/2.0 200 OK
321 {
322 "status" : "fail",
323 "data" : {
324 "performed_at" : "2014-10-18T20:04:37Z",
325 "runtime" : 10.37,
326 "output" : [
327 "Sending 5, 100-byte ICMP Echos to 192.0.2.5",
328 ".....",
329 "Success rate is 0 percent (0/5)"
330 ],
331 "format" : "text/plain",
332 "router" : "route-server.lookingglass.example.net"
333 }
334 }
336 2.3.3. Error
338 The status "error" represents an error which occurred in processing
339 the request or the command timed out. The response message must set
340 the "status" field to "error" and must contain the "message" key,
341 that keeps a meaningful message, explaining what went wrong.
343 The response may contain the "data" key, with required values listed
344 in Section 2.3.1. It may also include a "code" field, that carries a
345 numeric code corresponding to the error.
347 The HTTP status code should be 400 in case of a client-side error,
348 500 in case of a server-side error or 502 for errors occurring on the
349 target router. Code 504 should be used when a command timed out.
351 Example:
353 HTTP/1.1 400 Bad Request
354 {
355 "status" : "error",
356 "message" : "Unrecognized host or address."
357 }
359 3. Functions
361 The Looking Glass command set provides functions that are either
362 mandatory or optional to implement. The same principle applies to
363 the web-based Looking Glass.
365 It is not possible for any function to modify the server's state.
366 Therefore, all HTTP methods are GET operations.
368 Variables are templated and expanded in harmony of [RFC6570].
370 3.1. Diagnostic commands
372 3.1.1. Ping
374 Send echo messages to validate the reachability of a remote host and
375 measure round-trip time. The host can be a name or address.
377 Implementation of the ping command is mandatory.
379 Syntax: https://example.net/.well-known/looking-glass/v1/ping/{host}
380 Example query:
382 GET /.well-known/looking-glass/v1/ping/2001:DB8::35?protocol=2,1
383 Host: example.net
385 Example response:
387 HTTP/1.1 200 OK
388 {
389 "status" : "success",
390 "data" : {
391 "min" : 40,
392 "avg" : 41,
393 "max" : 44,
394 "rate" : 100,
395 "output" : [
396 "Sending 5, 100-byte ICMP Echos to 2001:DB8::35",
397 "!!!!!",
398 "Success rate is 100 percent (5/5)"
399 ],
400 "format" : "text/plain",
401 "performed_at" : "2014-10-04T14:40:58Z",
402 "runtime" : 0.77,
403 "router" : "c2951.lab.lg.example.net"
404 }
405 }
407 3.1.2. Traceroute
409 Trace path from the executing router to the destination host and list
410 all intermediate hops. The host can be a name or address.
412 Implementation of the traceroute command is optional.
414 Syntax: https://example.net/.well-known/looking-glass/v1/
415 traceroute/{host}
417 Example query:
419 GET /.well-known/looking-glass/v1/traceroute/192.0.2.8?routerindex=5
420 Host: example.net
421 Example response:
423 HTTP/1.1 200 OK
424 {
425 "status": "success",
426 "data": {
427 "output": [
428 "Tracing the route to 192.0.2.8",
429 "",
430 " 1 198.51.100.77 28 msec 28 msec 20 msec",
431 " 2 203.0.113.130 52 msec 40 msec 40 msec",
432 " 3 192.0.2.8 72 msec 76 msec 68 msec"
433 ],
434 "format": "text/plain",
435 "performed_at": "2018-06-10T12:09:31Z",
436 "runtime": 4.21,
437 "router": "c7206.lab.lg.example.net"
438 }
439 }
441 3.2. Informational commands
443 3.2.1. show route
445 Retrieve information about a specific subnet from the routing table.
447 Implementation of the "show route" command is mandatory.
449 Syntax: https://example.net/.well-known/looking-glass/v1/show/
450 route/{addr}
452 Example query:
454 GET /.well-known/looking-glass/v1/show/ [multiline]
455 route/2001:DB8::/48?protocol=2,1
456 Host: example.net
457 Example response:
459 HTTP/1.1 200 OK
460 {
461 "status": "success",
462 "data": {
463 "output": [
464 "S 2001:DB8::/48 [1/0]",
465 " via FE80::C007:CFF:FED9:17, FastEthernet0/0"
466 ],
467 "format": "text/plain",
468 "performed_at": "2018-06-11T17:13:39Z",
469 "runtime": 1.39,
470 "router": "c2951.lab.lg.example.net"
471 }
472 }
474 3.2.2. show bgp
476 Display matching record from BGP routing table. This should include
477 networks, next hop and may include metric, local preference, path
478 list, weight, etc.
480 Implementation of the "show bgp" command is optional.
482 Syntax: https://example.net/.well-known/looking-glass/v1/show/
483 bgp/{addr}
485 Example query:
487 GET /.well-known/looking-glass/v1/show/bgp/192.0.2.0/24
488 Host: example.net
489 Example response:
491 HTTP/1.1 200 OK
492 {
493 "status": "success",
494 "data": {
495 "output": [
496 "BGP routing table entry for 192.0.2.0/24, version 2",
497 "Paths: (2 available, best #2, table default)",
498 " Advertised to update-groups:",
499 " 1",
500 " Refresh Epoch 1",
501 " Local",
502 " 192.0.2.226 from 192.0.2.226 (192.0.2.226)",
503 " Origin IGP, metric 0, localpref 100, valid, internal",
504 "[...]"
505 ],
506 "format": "text/plain",
507 "performed_at": "2018-06-11T21:47:17Z",
508 "runtime": 2.03,
509 "router": "c2951.lab.lg.example.net"
510 }
511 }
513 3.2.3. show bgp summary
515 Print a summary of BGP neighbor status. This may include neighbor
516 BGP ID, autonomous system number, duration of peering, number of
517 received prefixes, etc.
519 Implementation of the "show bgp summary" command is optional.
521 Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
522 summary
524 Example:
526 GET /.well-known/looking-glass/v1/show/bgp/summary? [multiline]
527 protocol=2&routerindex=3
528 Host: example.net
529 Example response:
531 HTTP/1.1 200 OK
532 {
533 "status": "success",
534 "data": {
535 "output": [
536 "BGP router identifier 192.0.2.18, local AS number 64501",
537 "BGP table version is 85298, main routing table version 85298",
538 "50440 network entries using 867568 bytes of memory",
539 "[...]",
540 "Neighbor V AS MsgRcvd MsgSent TblVer Up/Down",
541 "2001:DB8:91::24 4 64500 481098 919095 85298 41w5d"
542 ],
543 "format": "text/plain",
544 "performed_at": "2018-06-11T21:59:21Z",
545 "runtime": 1.91,
546 "router": "c2951.lab.lg.example.net"
547 }
548 }
550 3.2.4. show bgp neighbors
552 Provide detailed information on BGP neighbor connections. Available
553 details may include neighbor BGP ID, advertised networks, learned
554 networks, autonomous system number, capabilities, protocol,
555 statistics, etc.
557 Implementation of the "show bgp neighbors" command is optional.
559 Syntax: https://example.net/.well-known/looking-glass/v1/show/bgp/
560 neighbors/{addr}
562 Example query:
564 GET /.well-known/looking-glass/v1/show/bgp/neighbors/192.0.2.226
565 Host: example.net
566 Example response:
568 HTTP/1.1 200 OK
569 {
570 "status": "success",
571 "data": {
572 "output": [
573 "BGP neighbor is 192.0.2.226, remote AS 64500, internal link",
574 " BGP version 4, remote router ID 198.51.100.31",
575 " BGP state = Established, up for 01:24:06",
576 "[...]"
577 ],
578 "format": "text/plain",
579 "performed_at": "2018-06-11T21:41:17Z",
580 "runtime": 1.87,
581 "router": "c2951.lab.lg.example.net"
582 }
583 }
585 3.3. Organizational commands
587 The following organizational commands must be included in the
588 implementation.
590 3.3.1. router list
592 The command provides a full list of routers that are available for
593 command execution. This list includes the router ID and its name.
594 It is equivalent to the common "router" HTML drop-down form element
595 and contains the same information.
597 Syntax: https://example.net/.well-known/looking-glass/v1/routers
599 Example response:
601 {
602 "status" : "success",
603 "data" : {
604 "routers" : [
605 "route-server.lookingglass.example.net",
606 "customer-edge.lookingglass.example.net",
607 "provider-edge.lookingglass.example.net"
608 ],
609 "performed_at" : "2014-10-19T20:07:01Z",
610 "runtime" : 0.73
611 }
612 }
614 3.3.2. router details
616 List additional information about the selected router, specified by
617 its router index. The response must contain the routers hostname and
618 router index. The response may contain more details like output
619 format, country code, city, administrative contact, vendor and model.
621 Available output formats are specified by Internet media type as of
622 [RFC6838] and listed in [IANA-MT]. If the routers support multiple
623 formats, they are separated by comma.
625 The router might provide output formats, that are not yet registered
626 or listed in [IANA-MT]. [RFC6838] provides a tree for unregistered
627 subtypes. For example, output in NETCONF format could use "text/
628 x.netconf".
630 Missing output format defaults to "text/plain", which is a copy of
631 the raw command-line output.
633 Syntax: https://example.net/.well-known/looking-glass/v1/
634 routers/{number}
636 Example query:
638 GET /.well-known/looking-glass/v1/routers/1
639 Host: example.net
641 Example response:
643 {
644 "status" : "success",
645 "data" : {
646 "id" : 1,
647 "name" : "customer-edge.lookingglass.example.net",
648 "format" : "text/plain,text/x.netconf",
649 "country" : "de",
650 "autonomous_system" : 64512
651 }
652 }
654 3.3.3. commands
656 This function provides a full list of commands that are available for
657 execution. The list includes mandatory, optional, and additional
658 (Section 3.4) commands. It is equivalent to the "command" HTML drop-
659 down or radio-button form element and contains the same information.
661 The list is formatted as "commands" array containing one object per
662 command. This object contains informative strings about the current
663 command: href, arguments, description and command.
665 Syntax: https://example.net/.well-known/looking-glass/v1/cmd
667 Example response:
669 {
670 "status" : "success",
671 "data" : {
672 "commands" : [
673 {
674 "href" : "https://example.net/.well-known/ [multiline]
675 looking-glass/v1/show/route",
676 "arguments" : "{addr}",
677 "description" : "Print records from IP routing table",
678 "command" : "show route"
679 },
680 {
681 "href" : "https://example.net/.well-known/ [multiline]
682 looking-glass/v1/traceroute",
683 "arguments" : "{addr}",
684 "description" : "Trace route to destination host",
685 "command" : "traceroute"
686 }
687 ]
688 }
689 }
691 3.4. Extensible commands
693 The list of commands may be expanded as long as the principles of
694 this document are observed.
696 For example, a Looking Glass provider may not be offering BGP-related
697 commands because of an OSPF-based network.
699 The sample command might be:
701 GET /.well-known/looking-glass/v1/show/ospf/database
702 Host: example.net
704 4. Miscellaneous
706 The network traffic sent by a "Looking Glass" is not appropriate when
707 measuring Service Level Agreements or validating Quality of Service
708 setting.
710 If a monitoring system uses the Looking Glass command set for
711 reachability checks, it should not rely on the HTTP status codes but
712 on the "status" message field inside the HTTP body.
714 5. IANA Considerations
716 5.1. Well-Known URIs Registry
718 This specification registers a Well-Known URI [RFC5785] (registration
719 pending):
721 URI Suffix: looking-glass
723 Change Controller: M.Stubbig
725 Specification Document(s): This document, Section 2
727 6. Security Consideration
729 The use of HTTPS is required to ensure a high level of security,
730 privacy, and confidentiality during transit.
732 6.1. Abuse Potential
734 The main goal of the Looking Glass command-set is the automated usage
735 of the Looking Glass service. This allows the scripting of API
736 calls, which could be used as a distributed Denial of Service (DDoS)
737 attack. It is recommended that implementers of the Looking Glass API
738 take steps to mitigate the above described abuse. The strategy can
739 include blocking or rate-limiting by client IP address or target IP
740 network.
742 6.2. Authentication
744 Authentication is not a requirement because the current Looking Glass
745 web services are usable without authentication. Requests to the
746 proposed API service may be authenticated by any method. The
747 decision is up to the implementers security requirements.
749 6.3. Minimal information
751 Some of the described commands provide a detailed insight into the
752 providers network. It is therefore up to the implementer's security
753 policy to dismiss commands that are marked as "optional" or restrict
754 commands that are marked as "mandatory".
756 7. References
758 7.1. Normative References
760 [IANA-AFN]
761 IANA, "Address Family Numbers", 2015,
762 .
765 [IANA-MT] IANA, "Media Types", 2015,
766 .
769 [IANA-SAFI]
770 IANA, "Subsequent Address Family Identifier (SAFI)
771 Parameters", 2015,
772 .
774 [JSend] OmniTI Labs, "JSend", 2014,
775 .
777 [RFC4760] Bates, T., Chandra, R., Katz, D., and Y. Rekhter,
778 "Multiprotocol Extensions for BGP-4", RFC 4760,
779 DOI 10.17487/RFC4760, January 2007,
780 .
782 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
783 Uniform Resource Identifiers (URIs)", RFC 5785,
784 DOI 10.17487/RFC5785, April 2010,
785 .
787 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
788 and D. Orchard, "URI Template", RFC 6570,
789 DOI 10.17487/RFC6570, March 2012,
790 .
792 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
793 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
794 DOI 10.17487/RFC7231, June 2014,
795 .
797 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
798 Interchange Format", STD 90, RFC 8259,
799 DOI 10.17487/RFC8259, December 2017,
800 .
802 7.2. Informative References
804 [iso8601] International Organization for Standardization, "Date and
805 time format--ISO 8601", 2006,
806 .
808 [RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix
809 Reserved for Documentation", RFC 3849,
810 DOI 10.17487/RFC3849, July 2004,
811 .
813 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks
814 Reserved for Documentation", RFC 5737,
815 DOI 10.17487/RFC5737, January 2010,
816 .
818 [RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names",
819 RFC 6761, DOI 10.17487/RFC6761, February 2013,
820 .
822 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
823 Specifications and Registration Procedures", BCP 13,
824 RFC 6838, DOI 10.17487/RFC6838, January 2013,
825 .
827 [RFC6996] Mitchell, J., "Autonomous System (AS) Reservation for
828 Private Use", BCP 6, RFC 6996, DOI 10.17487/RFC6996, July
829 2013, .
831 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
832 RFC 7320, DOI 10.17487/RFC7320, July 2014,
833 .
835 Appendix A. JSend
837 According to [JSend], "JSend is a specification that lays down some
838 rules for how JSON responses from web servers should be formatted.
839 JSend focuses on application-level (as opposed to protocol- or
840 transport-level) messaging which makes it ideal for use in REST-style
841 applications and APIs."
843 A basic JSend-compliant response must contain a "status" key and
844 should contain "data", "message" and "code" keys dependent on the
845 status value. The following table lists the required and optional
846 keys.
848 +---------+-----------------+---------------+
849 | Type | Required keys | Optional keys |
850 +---------+-----------------+---------------+
851 | success | status, data | |
852 | fail | status, data | |
853 | error | status, message | code, data |
854 +---------+-----------------+---------------+
856 Table 1: Type and keys in JSend response
858 Author's Address
860 Markus Stubbig
861 Independent
862 Germany
864 Email: stubbig.ietf@gmail.com