idnits 2.17.1
draft-mst-lgapi-09.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 :
----------------------------------------------------------------------------
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 697: '... use of HTTPS is REQUIRED to ensure a ...'
RFC 2119 keyword, line 708: '... It is RECOMMENDED that implementers...'
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (June 25, 2018) is 2125 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
** 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 June 25, 2018
5 Expires: December 27, 2018
7 Looking Glass command set
8 draft-mst-lgapi-09
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 December 27, 2018.
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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3
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 6. Security Consideration . . . . . . . . . . . . . . . . . . . 17
70 6.1. Abuse Potential . . . . . . . . . . . . . . . . . . . . . 17
71 6.2. Authentication . . . . . . . . . . . . . . . . . . . . . 17
72 6.3. Minimal information . . . . . . . . . . . . . . . . . . . 17
73 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
74 7.1. Normative References . . . . . . . . . . . . . . . . . . 17
75 7.2. Informative References . . . . . . . . . . . . . . . . . 18
76 Appendix A. JSend . . . . . . . . . . . . . . . . . . . . . . . 19
77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19
79 1. Introduction
81 Many Internet service providers (ISPs) and Internet exchange points
82 (IXPs) offer a complimentary web page to the general public, which
83 gives insights to the backbone routing table, BGP neighbor
84 information, or offered routes.
86 The visitor may also execute a ping or traceroute command to any
87 target address of their choice. Some ISPs even offer information
88 about their multicast routing table including the mtrace command.
89 The amount and type of offered information is not limited.
91 The service is mostly used for the purpose of troubleshooting and is
92 known under the term of "Looking Glass". The development of various
93 Looking Glass software packages has led to differences in the syntax,
94 style, and information that are available. The difference is of
95 minor interest to human users, but accessing a Looking Glass web page
96 by script is complicated, inefficient, and error-prone.
98 Accessing a Looking Glass service by script is required for repeating
99 tasks. It could be a monitoring system which validates link
100 availability or bandwidth usage.
102 This leads to the requirement of a unified access method to the
103 information provided by a Looking Glass. This document defines a
104 programmers interface, which provides a common schema, list of
105 arguments, and options when accessing a Looking Glass service.
107 The transport protocol of choice is encrypted HTTP, the style of
108 operation is REST, and the response format is JSON [RFC8259].
110 The Looking Glass command set is described as a language-independent
111 concept. Consequently, any programming language, which satisfies the
112 commands listed in the following chapters, is acceptable.
114 1.1. Background
116 The requirement of a uniform access to a Looking Glass service
117 becomes important when multiple Looking Glasses are part of a
118 monitoring system. Implementing a web client and HTTP-parser for
119 every kind of web-based Looking Glass is a time consuming workaround,
120 however, the Looking Glass command set is a much more viable,
121 compatible, and scalable solution.
123 1.2. Syntax Notation
125 This specification uses the JavaScript Object Notation (JSON) of
126 [RFC8259] arranged as JSend (Appendix A) compliant responses.
128 1.3. Examples
130 All URLs in this documentation use the reserved sample domain of
131 "example.net" as defined in [RFC6761] section 6.5.
133 IPv4 addresses use the documenational block of 192.0.2.0/24 [RFC5737]
134 and IPv6 addresses reside in the reserved prefix of 2001:DB8::/32
135 [RFC3849]. BGP Autonomous System numbers are chosen from the private
136 AS range defined in [RFC6996].
138 The examples skip some required parameters for reasons of simplicity.
140 2. Operation
142 A client issues a query using the HTTP GET method to request a
143 specific resources from the server. The resource is a URI and can be
144 informational or a command execution. The client must present all
145 necessary parameters for the server to execute the command on the
146 selected router. Every call is stateless and independent of the
147 previous one.
149 The "call" is a request from the client, which specifies a pre-
150 defined operation ("function") that the server will execute on a
151 selected router. The "command" is a task executed on the router and
152 initiated by the server on behalf of the client. The type and scope
153 of all commands is defined and limited by the server. The client
154 must not be able to execute random commands on the targeting router.
155 There must not be any direct communication between the client and the
156 router.
158 After the execution of the command on the selected router has
159 finished, the server replies to the client if the operation has
160 either succeeded, failed or timed out. The response is sent to the
161 client in JSON format. The communication protocol used between the
162 server and router is not specified by this document; any method (e.g.
163 Telnet, SSH, NETCONF, serial console) is acceptable.
165 All parameters and its values are case insensitive.
167 2.1. Method Parameters
169 Method parameters are mandatory components of the URI and placed in
170 the "path" section in terms of [RFC7320]. Basically, the method
171 parameters specify the call and determine which command the client
172 wants executed on the selected router.
174 2.2. Query Parameters
176 Query parameters are optional components of the URI and placed in the
177 "query" section in terms of [RFC7320]. Generally, the query
178 parameters are additional instructions for the requested command.
180 protocol
181 Restrict the command and method parameters to use the specified
182 protocol and version. Protocol is selected as "Address Family
183 Identifier" [IANA-AFN] [RFC4760] and optional "Subsequent Address
184 Family Identifier" [IANA-SAFI] separated by comma.
185 Default value is 1,1 (IP version 4, unicast).
186 JSON data type is String.
187 Examples:
189 * protocol=2,1 (IP version 6, unicast)
191 * protocol=26 (MPLS, no SAFI used)
193 router
194 Run the command on the router identified by its name. This is not
195 necessarily the router's hostname as long as the Looking Glass
196 software recognizes it.
197 Default value is the first router in the list of available
198 routers.
199 JSON data type is String.
200 Example: router=rbgn06.example.net
202 routerindex
203 Run the command on this router identified by its position in the
204 list of available routers.
205 Default value is "0".
206 JSON data type is Number.
207 Example: routerindex=8
209 random
210 Append a random string to prevent the client (or an intermediate
211 proxy) from caching the response. The server must ignore its
212 value.
213 No default value.
214 JSON data type is String.
215 Example: random=517A93B50
217 vrf
218 Run the command from the selected routing table. This parameter
219 is valid only on routers that support "Virtual Routing and
220 Forwarding" (VRF).
221 No default value.
222 JSON data type is String.
223 Example: vrf=mgmt
225 runtime
226 Stop executing the command after the runtime limit (in seconds) is
227 exceeded. A value of 0 disables the limit.
228 Default value is "30".
229 JSON data type is Number.
230 Example: runtime=60
232 format
233 Request the server to provide the output (if any) in the selected
234 format. Specify multiple formats separated by comma in descending
235 order of preference. See Section 3.3.2 for more details.
236 Default value is "text/plain" (raw/unformatted output).
237 JSON data type is String.
238 Example: format=application/yang,text/plain
240 2.3. Response
242 The HTTP response header contains an appropriate HTTP status code as
243 defined in [RFC7231] with the Content-Type set to "application/json".
245 The HTTP body contains details and error descriptions. The response
246 text must comply with the JSON syntax specification JSend, which is
247 briefly explained in Appendix A. Consequently every response must
248 contain a "status" field of either "success", "fail", or "error",
249 that are explained in the following sections.
251 2.3.1. Success
253 A successful response must set the "status" field to "success". It
254 must also contain a "data" object including the following
255 information:
257 performed_at
258 combined date and time in UTC ISO 8601 [iso8601] indicating when
259 the operation finished. This information must be present.
261 runtime
262 amount of seconds (wallclock) used to run the command. This
263 information must be present.
265 router
266 the name of the router, that executed the command. This
267 information may be present.
269 output
270 output of the command in a format that was requested by the client
271 or defaults to raw output as it appeared on the router's command
272 line interface (CLI). It might even be blank if the command did
273 not produce any output. This information should be present.
275 format
276 selected output format by the server. The client might request
277 multiple formats, so that the "Looking Glass" server has to choose
278 the best option and tell the client which format was selected.
279 This information should be present (or defaults to "text/plain" if
280 missing).
282 Adding more information to the response is permitted and must be
283 placed inside the "data" object.
285 The HTTP status code should be 200.
287 Example:
289 HTTP/1.1 200 OK
290 Content-Type: application/json
291 {
292 "status" : "success",
293 "data" : {
294 "router" : "route-server.lookingglass.example.net"
295 "performed_at" : "2014-10-15T17:15:34Z",
296 "runtime" : 2.63,
297 "output" : [
298 "full raw output from the observing router..."
299 ],
300 "format" : "text/plain"
301 }
302 }
304 2.3.2. Fail
306 A status of "fail" indicates that the selected command was executed
307 on the router but failed to succeed. The response message must set
308 the "status" field to "fail" and must contain the "data" object with
309 command-specific content, that is listed in Section 2.3.1.
311 The HTTP status code should be 200.
313 Example:
315 HTTP/2.0 200 OK
316 {
317 "status" : "fail",
318 "data" : {
319 "performed_at" : "2014-10-18T20:04:37Z",
320 "runtime" : 10.37,
321 "output" : [
322 "Sending 5, 100-byte ICMP Echos to 192.0.2.5",
323 ".....",
324 "Success rate is 0 percent (0/5)"
325 ],
326 "format" : "text/plain",
327 "router" : "route-server.lookingglass.example.net"
328 }
329 }
331 2.3.3. Error
333 The status "error" represents an error which occurred in processing
334 the request or the command timed out. The response message must set
335 the "status" field to "error" and must contain the "message" key,
336 that keeps a meaningful message, explaining what went wrong.
338 The response may contain the "data" key, with required values listed
339 in Section 2.3.1. It may also include a "code" field, that carries a
340 numeric code corresponding to the error.
342 The HTTP status code should be 400 in case of a client-side error,
343 500 in case of a server-side error or 502 for errors occurring on the
344 target router. Code 504 should be used when a command timed out.
346 Example:
348 HTTP/1.1 400 Bad Request
349 {
350 "status" : "error",
351 "message" : "Unrecognized host or address."
352 }
354 3. Functions
356 The Looking Glass command set provides functions that are either
357 mandatory or optional to implement. The same principle applies to
358 the web-based Looking Glass.
360 It is not possible for any function to modify the server's state.
361 Therefore, all HTTP methods are GET operations.
363 Variables are templated and expanded in harmony of [RFC6570].
365 3.1. Diagnostic commands
367 3.1.1. Ping
369 Send echo messages to validate the reachability of a remote host and
370 measure round-trip time. The host can be a name or address.
372 Implementation of the ping command is mandatory.
374 Syntax: https://lg.example.net/api/v1/ping/{host}
376 Example query:
378 https://lg.example.net/api/v1/ping/2001:DB8::35?protocol=2,1
379 Example response:
381 HTTP/1.1 200 OK
382 {
383 "status" : "success",
384 "data" : {
385 "min" : 40,
386 "avg" : 41,
387 "max" : 44,
388 "rate" : 100,
389 "output" : [
390 "Sending 5, 100-byte ICMP Echos to 2001:DB8::35",
391 "!!!!!",
392 "Success rate is 100 percent (5/5)"
393 ],
394 "format" : "text/plain",
395 "performed_at" : "2014-10-04T14:40:58Z",
396 "runtime" : 0.77,
397 "router" : "c2951.lab.lgapi.example.net"
398 }
399 }
401 3.1.2. Traceroute
403 Trace path from the executing router to the destination host and list
404 all intermediate hops. The host can be a name or address.
406 Implementation of the traceroute command is optional.
408 Syntax: https://lg.example.net/api/v1/traceroute/{host}
410 Example query:
412 https://lg.example.net/api/v1/traceroute/192.0.2.8?routerindex=5
413 Example response:
415 HTTP/1.1 200 OK
416 {
417 "status": "success",
418 "data": {
419 "output": [
420 "Tracing the route to 192.0.2.8",
421 "",
422 " 1 198.51.100.77 28 msec 28 msec 20 msec",
423 " 2 203.0.113.130 52 msec 40 msec 40 msec",
424 " 3 192.0.2.8 72 msec 76 msec 68 msec"
425 ],
426 "format": "text/plain",
427 "performed_at": "2018-06-10T12:09:31Z",
428 "runtime": 4.21,
429 "router": "c7206.lab.lgapi.example.net"
430 }
431 }
433 3.2. Informational commands
435 3.2.1. show route
437 Retrieve information about a specific subnet from the routing table.
439 Implementation of the "show route" command is mandatory.
441 Syntax: https://lg.example.net/api/v1/show/route/{addr}
443 Example query:
445 https://lg.example.net/api/v1/show/route/2001:DB8::/48?protocol=2,1
446 Example response:
448 HTTP/1.1 200 OK
449 {
450 "status": "success",
451 "data": {
452 "output": [
453 "S 2001:DB8::/48 [1/0]",
454 " via FE80::C007:CFF:FED9:17, FastEthernet0/0"
455 ],
456 "format": "text/plain",
457 "performed_at": "2018-06-11T17:13:39Z",
458 "runtime": 1.39,
459 "router": "c2951.lab.lgapi.example.net"
460 }
461 }
463 3.2.2. show bgp
465 Display matching record from BGP routing table. This should include
466 networks, next hop and may include metric, local preference, path
467 list, weight, etc.
469 Implementation of the "show bgp" command is optional.
471 Syntax: https://lg.example.net/api/v1/show/bgp/{addr}
473 Example query:
475 https://lg.example.net/api/v1/show/bgp/192.0.2.0/24
476 Example response:
478 HTTP/1.1 200 OK
479 {
480 "status": "success",
481 "data": {
482 "output": [
483 "BGP routing table entry for 192.0.2.0/24, version 2",
484 "Paths: (2 available, best #2, table default)",
485 " Advertised to update-groups:",
486 " 1",
487 " Refresh Epoch 1",
488 " Local",
489 " 192.0.2.226 from 192.0.2.226 (192.0.2.226)",
490 " Origin IGP, metric 0, localpref 100, valid, internal",
491 "[...]"
492 ],
493 "format": "text/plain",
494 "performed_at": "2018-06-11T21:47:17Z",
495 "runtime": 2.03,
496 "router": "c2951.lab.lgapi.example.net"
497 }
498 }
500 3.2.3. show bgp summary
502 Print a summary of BGP neighbor status. This may include neighbor
503 BGP ID, autonomous system number, duration of peering, number of
504 received prefixes, etc.
506 Implementation of the "show bgp summary" command is optional.
508 Syntax: https://lg.example.net/api/v1/show/bgp/summary
510 Example:
512 https://example.net/api/v1/show/bgp/summary?protocol=2&routerindex=3
513 Example response:
515 HTTP/1.1 200 OK
516 {
517 "status": "success",
518 "data": {
519 "output": [
520 "BGP router identifier 192.0.2.18, local AS number 64501",
521 "BGP table version is 85298, main routing table version 85298",
522 "50440 network entries using 867568 bytes of memory",
523 "[...]",
524 "Neighbor V AS MsgRcvd MsgSent TblVer Up/Down",
525 "2001:DB8:91::24 4 64500 481098 919095 85298 41w5d"
526 ],
527 "format": "text/plain",
528 "performed_at": "2018-06-11T21:59:21Z",
529 "runtime": 1.91,
530 "router": "c2951.lab.lgapi.example.net"
531 }
532 }
534 3.2.4. show bgp neighbors
536 Provide detailed information on BGP neighbor connections. Available
537 details may include neighbor BGP ID, advertised networks, learned
538 networks, autonomous system number, capabilities, protocol,
539 statistics, etc.
541 Implementation of the "show bgp neighbors" command is optional.
543 Syntax: https://lg.example.net/api/v1/show/bgp/neighbors/{addr}
545 Example query:
547 https://lg.example.net/api/v1/show/bgp/neighbors/192.0.2.226
548 Example response:
550 HTTP/1.1 200 OK
551 {
552 "status": "success",
553 "data": {
554 "output": [
555 "BGP neighbor is 192.0.2.226, remote AS 64500, internal link",
556 " BGP version 4, remote router ID 198.51.100.31",
557 " BGP state = Established, up for 01:24:06",
558 "[...]"
559 ],
560 "format": "text/plain",
561 "performed_at": "2018-06-11T21:41:17Z",
562 "runtime": 1.87,
563 "router": "c2951.lab.lgapi.example.net"
564 }
565 }
567 3.3. Organizational commands
569 The following organizational commands must be included in the
570 implementation.
572 3.3.1. router list
574 The command provides a full list of routers that are available for
575 command execution. This list includes the router ID and its name.
576 It is equivalent to the common "router" HTML drop-down form element
577 and contains the same information.
579 Syntax: https://lg.example.net/api/v1/routers
581 Example response:
583 {
584 "status" : "success",
585 "data" : {
586 "routers" : [
587 "route-server.lookingglass.example.net",
588 "customer-edge.lookingglass.example.net",
589 "provider-edge.lookingglass.example.net"
590 ],
591 "performed_at" : "2014-10-19T20:07:01Z",
592 "runtime" : 0.73
593 }
594 }
596 3.3.2. router details
598 List additional information about the selected router, specified by
599 its router index. The response must contain the routers hostname and
600 router index. The response may contain more details like output
601 format, country code, city, administrative contact, vendor and model.
603 Available output formats are specified by Internet media type as of
604 [RFC6838] and listed in [IANA-MT]. If the routers supports multiple
605 formats, they are separated by comma.
607 The router might provide output formats, that are not yet registered
608 or listed in [IANA-MT]. [RFC6838] provides a tree for unregistered
609 subtypes. For example, output in NETCONF format could use "text/
610 x.netconf".
612 Missing output format defaults to "text/plain", which is a copy of
613 the raw command-line output.
615 Syntax: https://lg.example.net/api/v1/routers/{number}
617 Example query:
619 https://lg.example.net/api/v1/routers/1
621 Example response:
623 {
624 "status" : "success",
625 "data" : {
626 "id" : 1,
627 "name" : "customer-edge.lookingglass.example.net",
628 "format" : "text/plain,text/x.netconf",
629 "country" : "de",
630 "autonomous_system" : 64512
631 }
632 }
634 3.3.3. commands
636 This function provides a full list of commands that are available for
637 execution. The list includes mandatory, optional, and additional
638 (Section 3.4) commands. It is equivalent to the "command" HTML drop-
639 down or radio-button form element and contains the same information.
641 The list is formatted as "commands" array containing one object per
642 command. This object contains informative strings about the current
643 command: href, arguments, description and command.
645 Syntax: https://lg.example.net/api/v1/commands
647 Example response:
649 {
650 "status" : "success",
651 "data" : {
652 "commands" : [
653 {
654 "href" : "https://lg.example.net/api/v1/show/route",
655 "arguments" : "{addr}",
656 "description" : "Print records from IP routing table",
657 "command" : "show route"
658 },
659 {
660 "href" : "https://lg.example.net/api/v1/traceroute",
661 "arguments" : "{addr}",
662 "description" : "Trace route to destination host",
663 "command" : "traceroute"
664 }
665 ]
666 }
667 }
669 3.4. Extensible commands
671 The list of commands may be expanded as long as the principles of
672 this document are observed.
674 For example, a Looking Glass provider may not be offering BGP-related
675 commands because of an OSPF-based network.
677 The sample command might be:
679 https://lg.example.net/api/v1/show/ospf/database
681 4. Miscellaneous
683 The network traffic sent by a "Looking Glass" is not appropriate when
684 measuring Service Level Agreements or validating Quality of Service
685 setting.
687 If a monitoring system uses the Looking Glass command set for
688 reachability checks, it should not rely on the HTTP status codes but
689 on the "status" message field inside the HTTP body.
691 5. IANA Considerations
693 This document makes no requests for IANA action.
695 6. Security Consideration
697 The use of HTTPS is REQUIRED to ensure a high level of security,
698 privacy, and confidentiality during transit.
700 6.1. Abuse Potential
702 The main goal of the Looking Glass command-set is the automated usage
703 of the Looking Glass service. This allows the scripting of API
704 calls, which could be used as a distributed Denial of Service (DDoS)
705 attack. Interestingly, the attacked system recognizes the attack
706 originating from various ISPs core network.
708 It is RECOMMENDED that implementers of the Looking Glass API take
709 steps to mitigate the above described abuse. The strategy can
710 include blocking or rate-limiting by client IP address or target IP
711 network.
713 6.2. Authentication
715 Authentication is not a requirement because the current Looking Glass
716 web services are usable without authentication. Requests to the
717 proposed API service may be authenticated by any method. The
718 decision is up to the implementers security requirements.
720 6.3. Minimal information
722 Some of the described commands provide a detailed insight into the
723 providers network. It is therefore up to the implementer's security
724 policy to dismiss commands that are marked as "optional" or restrict
725 commands that are marked as "mandatory".
727 7. References
729 7.1. Normative References
731 [IANA-AFN]
732 IANA, "Address Family Numbers", 2015,
733 .
736 [IANA-MT] IANA, "Media Types", 2015,
737 .
740 [IANA-SAFI]
741 IANA, "Subsequent Address Family Identifier (SAFI)
742 Parameters", 2015,
743 .
745 [JSend] OmniTI Labs, "JSend", 2014,
746 .
748 [RFC4760] Bates, T., Chandra, R., Katz, D., and Y. Rekhter,
749 "Multiprotocol Extensions for BGP-4", RFC 4760,
750 DOI 10.17487/RFC4760, January 2007,
751 .
753 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
754 and D. Orchard, "URI Template", RFC 6570,
755 DOI 10.17487/RFC6570, March 2012,
756 .
758 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
759 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
760 DOI 10.17487/RFC7231, June 2014,
761 .
763 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
764 Interchange Format", STD 90, RFC 8259,
765 DOI 10.17487/RFC8259, December 2017,
766 .
768 7.2. Informative References
770 [iso8601] International Organization for Standardization, "Date and
771 time format--ISO 8601", 2006,
772 .
774 [RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix
775 Reserved for Documentation", RFC 3849,
776 DOI 10.17487/RFC3849, July 2004,
777 .
779 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks
780 Reserved for Documentation", RFC 5737,
781 DOI 10.17487/RFC5737, January 2010,
782 .
784 [RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names",
785 RFC 6761, DOI 10.17487/RFC6761, February 2013,
786 .
788 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
789 Specifications and Registration Procedures", BCP 13,
790 RFC 6838, DOI 10.17487/RFC6838, January 2013,
791 .
793 [RFC6996] Mitchell, J., "Autonomous System (AS) Reservation for
794 Private Use", BCP 6, RFC 6996, DOI 10.17487/RFC6996, July
795 2013, .
797 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
798 RFC 7320, DOI 10.17487/RFC7320, July 2014,
799 .
801 Appendix A. JSend
803 According to [JSend], "JSend is a specification that lays down some
804 rules for how JSON responses from web servers should be formatted.
805 JSend focuses on application-level (as opposed to protocol- or
806 transport-level) messaging which makes it ideal for use in REST-style
807 applications and APIs."
809 A basic JSend-compliant response must contain a "status" key and
810 should contain "data", "message" and "code" keys dependent on the
811 status value. The following table lists the required and optional
812 keys.
814 +---------+-----------------+---------------+
815 | Type | Required keys | Optional keys |
816 +---------+-----------------+---------------+
817 | success | status, data | |
818 | fail | status, data | |
819 | error | status, message | code, data |
820 +---------+-----------------+---------------+
822 Table 1: Type and keys in JSend response
824 Author's Address
826 Markus Stubbig
827 Independent
828 Germany
830 Email: stubbig.ietf@gmail.com