idnits 2.17.1
draft-mst-lgapi-10.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 (August 23, 2018) is 2072 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: 1 error (**), 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 August 23, 2018
5 Expires: February 24, 2019
7 Looking Glass command set
8 draft-mst-lgapi-10
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 February 24, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3
59 2.1. Method Parameters . . . . . . . . . . . . . . . . . . . . 4
60 2.2. Query Parameters . . . . . . . . . . . . . . . . . . . . 4
61 2.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 5
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-based service to their customers and
83 the general public that gives insights to the backbone routing table,
84 BGP neighbor information, or offered routes. This service is known
85 as a "Network Looking Glass". Because they utilize a web-based
86 interface it is hard to automate access to the services and make that
87 automation transferable between different service implementations.
89 This document describes a common command set to provide application
90 programmers uniform access to Looking Glass services.
92 The commands are intended to provide the same level of information as
93 available via web-based interfaces, but to do so in a computer-
94 readable format. The intention is that multiple implementers of
95 Looking Glass services can provide access through these commands so
96 that an application can make use of the different implementations.
98 The command set is split into mandatory-to-support, optional, and
99 additional. The commands are extensible for new features and for
100 value-add by implementations.
102 The Looking Glass command set is described as a language-independent
103 concept. Consequently, any programming language, which satisfies the
104 commands listed in the following chapters, is acceptable.
106 This work is not the output of the IETF and is presented in the hope
107 that Looking Glass implementers will offer a common programmable
108 interface.
110 1.1. Background
112 The requirement of a uniform access to a Looking Glass service
113 becomes important when multiple Looking Glasses are part of a
114 monitoring system. Implementing a web client and HTTP-parser for
115 every kind of web-based Looking Glass is a time consuming workaround,
116 however, the Looking Glass command set is a much more viable,
117 compatible, and scalable solution.
119 1.2. Syntax Notation
121 This specification uses the JavaScript Object Notation (JSON) of
122 [RFC8259] arranged as JSend (Appendix A) compliant responses.
124 1.3. Examples
126 All URLs in this documentation use the reserved sample domain of
127 "example.net" as defined in [RFC6761] section 6.5.
129 IPv4 addresses use the documenational block of 192.0.2.0/24 [RFC5737]
130 and IPv6 addresses reside in the reserved prefix of 2001:DB8::/32
131 [RFC3849]. BGP Autonomous System numbers are chosen from the private
132 AS range defined in [RFC6996].
134 The examples skip some required parameters for reasons of simplicity.
136 2. Operation
138 A client issues a query using the HTTP GET method to request a
139 specific resources from the server. The resource is a URI and can be
140 informational or a command execution. The client must present all
141 necessary parameters for the server to execute the command on the
142 selected router. Every call is stateless and independent of the
143 previous one.
145 The "call" is a request from the client, which specifies a pre-
146 defined operation ("function") that the server will execute on a
147 selected router. The "command" is a task executed on the router and
148 initiated by the server on behalf of the client. The type and scope
149 of all commands is defined and limited by the server. The client
150 must not be able to execute random commands on the targeting router.
151 There must not be any direct communication between the client and the
152 router.
154 After the execution of the command on the selected router has
155 finished, the server replies to the client if the operation has
156 either succeeded, failed or timed out. The response is sent to the
157 client in JSON format. The communication protocol used between the
158 server and router is not specified by this document; any method (e.g.
159 Telnet, SSH, NETCONF, serial console) is acceptable.
161 All parameters and its values are case insensitive.
163 2.1. Method Parameters
165 Method parameters are mandatory components of the URI and placed in
166 the "path" section in terms of [RFC7320]. Basically, the method
167 parameters specify the call and determine which command the client
168 wants executed on the selected router.
170 2.2. Query Parameters
172 Query parameters are optional components of the URI and placed in the
173 "query" section in terms of [RFC7320]. Generally, the query
174 parameters are additional instructions for the requested command.
176 protocol
177 Restrict the command and method parameters to use the specified
178 protocol and version. Protocol is selected as "Address Family
179 Identifier" [IANA-AFN] [RFC4760] and optional "Subsequent Address
180 Family Identifier" [IANA-SAFI] separated by comma.
181 Default value is 1,1 (IP version 4, unicast).
182 JSON data type is String.
183 Examples:
185 * protocol=2,1 (IP version 6, unicast)
187 * protocol=26 (MPLS, no SAFI used)
189 router
190 Run the command on the router identified by its name. This is not
191 necessarily the router's hostname as long as the Looking Glass
192 software recognizes it.
194 Default value is the first router in the list of available
195 routers.
196 JSON data type is String.
197 Example: router=rbgn06.example.net
199 routerindex
200 Run the command on this router identified by its position in the
201 list of available routers.
202 Default value is "0".
203 JSON data type is Number.
204 Example: routerindex=8
206 random
207 Append a random string to prevent the client (or an intermediate
208 proxy) from caching the response. The server must ignore its
209 value.
210 No default value.
211 JSON data type is String.
212 Example: random=517A93B50
214 vrf
215 Run the command from the selected routing table. This parameter
216 is valid only on routers that support "Virtual Routing and
217 Forwarding" (VRF).
218 No default value.
219 JSON data type is String.
220 Example: vrf=mgmt
222 runtime
223 Stop executing the command after the runtime limit (in seconds) is
224 exceeded. A value of 0 disables the limit.
225 Default value is "30".
226 JSON data type is Number.
227 Example: runtime=60
229 format
230 Request the server to provide the output (if any) in the selected
231 format. Specify multiple formats separated by comma in descending
232 order of preference. See Section 3.3.2 for more details.
233 Default value is "text/plain" (raw/unformatted output).
234 JSON data type is String.
235 Example: format=application/yang,text/plain
237 2.3. Response
239 The HTTP response header contains an appropriate HTTP status code as
240 defined in [RFC7231] with the Content-Type set to "application/json".
242 The HTTP body contains details and error descriptions. The response
243 text must comply with the JSON syntax specification JSend, which is
244 briefly explained in Appendix A. Consequently every response must
245 contain a "status" field of either "success", "fail", or "error",
246 that are explained in the following sections.
248 2.3.1. Success
250 A successful response must set the "status" field to "success". It
251 must also contain a "data" object including the following
252 information:
254 performed_at
255 combined date and time in UTC ISO 8601 [iso8601] indicating when
256 the operation finished. This information must be present.
258 runtime
259 amount of seconds (wallclock) used to run the command. This
260 information must be present.
262 router
263 the name of the router, that executed the command. This
264 information may be present.
266 output
267 output of the command in a format that was requested by the client
268 or defaults to raw output as it appeared on the router's command
269 line interface (CLI). It might even be blank if the command did
270 not produce any output. This information should be present.
272 format
273 selected output format by the server. The client might request
274 multiple formats, so that the "Looking Glass" server has to choose
275 the best option and tell the client which format was selected.
276 This information should be present (or defaults to "text/plain" if
277 missing).
279 Adding more information to the response is permitted and must be
280 placed inside the "data" object.
282 The HTTP status code should be 200.
284 Example:
286 HTTP/1.1 200 OK
287 Content-Type: application/json
288 {
289 "status" : "success",
290 "data" : {
291 "router" : "route-server.lookingglass.example.net"
292 "performed_at" : "2014-10-15T17:15:34Z",
293 "runtime" : 2.63,
294 "output" : [
295 "full raw output from the observing router..."
296 ],
297 "format" : "text/plain"
298 }
299 }
301 2.3.2. Fail
303 A status of "fail" indicates that the selected command was executed
304 on the router but failed to succeed. The response message must set
305 the "status" field to "fail" and must contain the "data" object with
306 command-specific content, that is listed in Section 2.3.1.
308 The HTTP status code should be 200.
310 Example:
312 HTTP/2.0 200 OK
313 {
314 "status" : "fail",
315 "data" : {
316 "performed_at" : "2014-10-18T20:04:37Z",
317 "runtime" : 10.37,
318 "output" : [
319 "Sending 5, 100-byte ICMP Echos to 192.0.2.5",
320 ".....",
321 "Success rate is 0 percent (0/5)"
322 ],
323 "format" : "text/plain",
324 "router" : "route-server.lookingglass.example.net"
325 }
326 }
328 2.3.3. Error
330 The status "error" represents an error which occurred in processing
331 the request or the command timed out. The response message must set
332 the "status" field to "error" and must contain the "message" key,
333 that keeps a meaningful message, explaining what went wrong.
335 The response may contain the "data" key, with required values listed
336 in Section 2.3.1. It may also include a "code" field, that carries a
337 numeric code corresponding to the error.
339 The HTTP status code should be 400 in case of a client-side error,
340 500 in case of a server-side error or 502 for errors occurring on the
341 target router. Code 504 should be used when a command timed out.
343 Example:
345 HTTP/1.1 400 Bad Request
346 {
347 "status" : "error",
348 "message" : "Unrecognized host or address."
349 }
351 3. Functions
353 The Looking Glass command set provides functions that are either
354 mandatory or optional to implement. The same principle applies to
355 the web-based Looking Glass.
357 It is not possible for any function to modify the server's state.
358 Therefore, all HTTP methods are GET operations.
360 Variables are templated and expanded in harmony of [RFC6570].
362 3.1. Diagnostic commands
364 3.1.1. Ping
366 Send echo messages to validate the reachability of a remote host and
367 measure round-trip time. The host can be a name or address.
369 Implementation of the ping command is mandatory.
371 Syntax: https://lg.example.net/api/v1/ping/{host}
373 Example query:
375 https://lg.example.net/api/v1/ping/2001:DB8::35?protocol=2,1
376 Example response:
378 HTTP/1.1 200 OK
379 {
380 "status" : "success",
381 "data" : {
382 "min" : 40,
383 "avg" : 41,
384 "max" : 44,
385 "rate" : 100,
386 "output" : [
387 "Sending 5, 100-byte ICMP Echos to 2001:DB8::35",
388 "!!!!!",
389 "Success rate is 100 percent (5/5)"
390 ],
391 "format" : "text/plain",
392 "performed_at" : "2014-10-04T14:40:58Z",
393 "runtime" : 0.77,
394 "router" : "c2951.lab.lgapi.example.net"
395 }
396 }
398 3.1.2. Traceroute
400 Trace path from the executing router to the destination host and list
401 all intermediate hops. The host can be a name or address.
403 Implementation of the traceroute command is optional.
405 Syntax: https://lg.example.net/api/v1/traceroute/{host}
407 Example query:
409 https://lg.example.net/api/v1/traceroute/192.0.2.8?routerindex=5
410 Example response:
412 HTTP/1.1 200 OK
413 {
414 "status": "success",
415 "data": {
416 "output": [
417 "Tracing the route to 192.0.2.8",
418 "",
419 " 1 198.51.100.77 28 msec 28 msec 20 msec",
420 " 2 203.0.113.130 52 msec 40 msec 40 msec",
421 " 3 192.0.2.8 72 msec 76 msec 68 msec"
422 ],
423 "format": "text/plain",
424 "performed_at": "2018-06-10T12:09:31Z",
425 "runtime": 4.21,
426 "router": "c7206.lab.lgapi.example.net"
427 }
428 }
430 3.2. Informational commands
432 3.2.1. show route
434 Retrieve information about a specific subnet from the routing table.
436 Implementation of the "show route" command is mandatory.
438 Syntax: https://lg.example.net/api/v1/show/route/{addr}
440 Example query:
442 https://lg.example.net/api/v1/show/route/2001:DB8::/48?protocol=2,1
443 Example response:
445 HTTP/1.1 200 OK
446 {
447 "status": "success",
448 "data": {
449 "output": [
450 "S 2001:DB8::/48 [1/0]",
451 " via FE80::C007:CFF:FED9:17, FastEthernet0/0"
452 ],
453 "format": "text/plain",
454 "performed_at": "2018-06-11T17:13:39Z",
455 "runtime": 1.39,
456 "router": "c2951.lab.lgapi.example.net"
457 }
458 }
460 3.2.2. show bgp
462 Display matching record from BGP routing table. This should include
463 networks, next hop and may include metric, local preference, path
464 list, weight, etc.
466 Implementation of the "show bgp" command is optional.
468 Syntax: https://lg.example.net/api/v1/show/bgp/{addr}
470 Example query:
472 https://lg.example.net/api/v1/show/bgp/192.0.2.0/24
473 Example response:
475 HTTP/1.1 200 OK
476 {
477 "status": "success",
478 "data": {
479 "output": [
480 "BGP routing table entry for 192.0.2.0/24, version 2",
481 "Paths: (2 available, best #2, table default)",
482 " Advertised to update-groups:",
483 " 1",
484 " Refresh Epoch 1",
485 " Local",
486 " 192.0.2.226 from 192.0.2.226 (192.0.2.226)",
487 " Origin IGP, metric 0, localpref 100, valid, internal",
488 "[...]"
489 ],
490 "format": "text/plain",
491 "performed_at": "2018-06-11T21:47:17Z",
492 "runtime": 2.03,
493 "router": "c2951.lab.lgapi.example.net"
494 }
495 }
497 3.2.3. show bgp summary
499 Print a summary of BGP neighbor status. This may include neighbor
500 BGP ID, autonomous system number, duration of peering, number of
501 received prefixes, etc.
503 Implementation of the "show bgp summary" command is optional.
505 Syntax: https://lg.example.net/api/v1/show/bgp/summary
507 Example:
509 https://example.net/api/v1/show/bgp/summary?protocol=2&routerindex=3
510 Example response:
512 HTTP/1.1 200 OK
513 {
514 "status": "success",
515 "data": {
516 "output": [
517 "BGP router identifier 192.0.2.18, local AS number 64501",
518 "BGP table version is 85298, main routing table version 85298",
519 "50440 network entries using 867568 bytes of memory",
520 "[...]",
521 "Neighbor V AS MsgRcvd MsgSent TblVer Up/Down",
522 "2001:DB8:91::24 4 64500 481098 919095 85298 41w5d"
523 ],
524 "format": "text/plain",
525 "performed_at": "2018-06-11T21:59:21Z",
526 "runtime": 1.91,
527 "router": "c2951.lab.lgapi.example.net"
528 }
529 }
531 3.2.4. show bgp neighbors
533 Provide detailed information on BGP neighbor connections. Available
534 details may include neighbor BGP ID, advertised networks, learned
535 networks, autonomous system number, capabilities, protocol,
536 statistics, etc.
538 Implementation of the "show bgp neighbors" command is optional.
540 Syntax: https://lg.example.net/api/v1/show/bgp/neighbors/{addr}
542 Example query:
544 https://lg.example.net/api/v1/show/bgp/neighbors/192.0.2.226
545 Example response:
547 HTTP/1.1 200 OK
548 {
549 "status": "success",
550 "data": {
551 "output": [
552 "BGP neighbor is 192.0.2.226, remote AS 64500, internal link",
553 " BGP version 4, remote router ID 198.51.100.31",
554 " BGP state = Established, up for 01:24:06",
555 "[...]"
556 ],
557 "format": "text/plain",
558 "performed_at": "2018-06-11T21:41:17Z",
559 "runtime": 1.87,
560 "router": "c2951.lab.lgapi.example.net"
561 }
562 }
564 3.3. Organizational commands
566 The following organizational commands must be included in the
567 implementation.
569 3.3.1. router list
571 The command provides a full list of routers that are available for
572 command execution. This list includes the router ID and its name.
573 It is equivalent to the common "router" HTML drop-down form element
574 and contains the same information.
576 Syntax: https://lg.example.net/api/v1/routers
578 Example response:
580 {
581 "status" : "success",
582 "data" : {
583 "routers" : [
584 "route-server.lookingglass.example.net",
585 "customer-edge.lookingglass.example.net",
586 "provider-edge.lookingglass.example.net"
587 ],
588 "performed_at" : "2014-10-19T20:07:01Z",
589 "runtime" : 0.73
590 }
591 }
593 3.3.2. router details
595 List additional information about the selected router, specified by
596 its router index. The response must contain the routers hostname and
597 router index. The response may contain more details like output
598 format, country code, city, administrative contact, vendor and model.
600 Available output formats are specified by Internet media type as of
601 [RFC6838] and listed in [IANA-MT]. If the routers supports multiple
602 formats, they are separated by comma.
604 The router might provide output formats, that are not yet registered
605 or listed in [IANA-MT]. [RFC6838] provides a tree for unregistered
606 subtypes. For example, output in NETCONF format could use "text/
607 x.netconf".
609 Missing output format defaults to "text/plain", which is a copy of
610 the raw command-line output.
612 Syntax: https://lg.example.net/api/v1/routers/{number}
614 Example query:
616 https://lg.example.net/api/v1/routers/1
618 Example response:
620 {
621 "status" : "success",
622 "data" : {
623 "id" : 1,
624 "name" : "customer-edge.lookingglass.example.net",
625 "format" : "text/plain,text/x.netconf",
626 "country" : "de",
627 "autonomous_system" : 64512
628 }
629 }
631 3.3.3. commands
633 This function provides a full list of commands that are available for
634 execution. The list includes mandatory, optional, and additional
635 (Section 3.4) commands. It is equivalent to the "command" HTML drop-
636 down or radio-button form element and contains the same information.
638 The list is formatted as "commands" array containing one object per
639 command. This object contains informative strings about the current
640 command: href, arguments, description and command.
642 Syntax: https://lg.example.net/api/v1/commands
644 Example response:
646 {
647 "status" : "success",
648 "data" : {
649 "commands" : [
650 {
651 "href" : "https://lg.example.net/api/v1/show/route",
652 "arguments" : "{addr}",
653 "description" : "Print records from IP routing table",
654 "command" : "show route"
655 },
656 {
657 "href" : "https://lg.example.net/api/v1/traceroute",
658 "arguments" : "{addr}",
659 "description" : "Trace route to destination host",
660 "command" : "traceroute"
661 }
662 ]
663 }
664 }
666 3.4. Extensible commands
668 The list of commands may be expanded as long as the principles of
669 this document are observed.
671 For example, a Looking Glass provider may not be offering BGP-related
672 commands because of an OSPF-based network.
674 The sample command might be:
676 https://lg.example.net/api/v1/show/ospf/database
678 4. Miscellaneous
680 The network traffic sent by a "Looking Glass" is not appropriate when
681 measuring Service Level Agreements or validating Quality of Service
682 setting.
684 If a monitoring system uses the Looking Glass command set for
685 reachability checks, it should not rely on the HTTP status codes but
686 on the "status" message field inside the HTTP body.
688 5. IANA Considerations
690 This document makes no requests for IANA action.
692 6. Security Consideration
694 The use of HTTPS is required to ensure a high level of security,
695 privacy, and confidentiality during transit.
697 6.1. Abuse Potential
699 The main goal of the Looking Glass command-set is the automated usage
700 of the Looking Glass service. This allows the scripting of API
701 calls, which could be used as a distributed Denial of Service (DDoS)
702 attack. Interestingly, the attacked system recognizes the attack
703 originating from various ISPs core network.
705 It is recommended that implementers of the Looking Glass API take
706 steps to mitigate the above described abuse. The strategy can
707 include blocking or rate-limiting by client IP address or target IP
708 network.
710 6.2. Authentication
712 Authentication is not a requirement because the current Looking Glass
713 web services are usable without authentication. Requests to the
714 proposed API service may be authenticated by any method. The
715 decision is up to the implementers security requirements.
717 6.3. Minimal information
719 Some of the described commands provide a detailed insight into the
720 providers network. It is therefore up to the implementer's security
721 policy to dismiss commands that are marked as "optional" or restrict
722 commands that are marked as "mandatory".
724 7. References
726 7.1. Normative References
728 [IANA-AFN]
729 IANA, "Address Family Numbers", 2015,
730 .
733 [IANA-MT] IANA, "Media Types", 2015,
734 .
737 [IANA-SAFI]
738 IANA, "Subsequent Address Family Identifier (SAFI)
739 Parameters", 2015,
740 .
742 [JSend] OmniTI Labs, "JSend", 2014,
743 .
745 [RFC4760] Bates, T., Chandra, R., Katz, D., and Y. Rekhter,
746 "Multiprotocol Extensions for BGP-4", RFC 4760,
747 DOI 10.17487/RFC4760, January 2007,
748 .
750 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
751 and D. Orchard, "URI Template", RFC 6570,
752 DOI 10.17487/RFC6570, March 2012,
753 .
755 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
756 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
757 DOI 10.17487/RFC7231, June 2014,
758 .
760 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
761 Interchange Format", STD 90, RFC 8259,
762 DOI 10.17487/RFC8259, December 2017,
763 .
765 7.2. Informative References
767 [iso8601] International Organization for Standardization, "Date and
768 time format--ISO 8601", 2006,
769 .
771 [RFC3849] Huston, G., Lord, A., and P. Smith, "IPv6 Address Prefix
772 Reserved for Documentation", RFC 3849,
773 DOI 10.17487/RFC3849, July 2004,
774 .
776 [RFC5737] Arkko, J., Cotton, M., and L. Vegoda, "IPv4 Address Blocks
777 Reserved for Documentation", RFC 5737,
778 DOI 10.17487/RFC5737, January 2010,
779 .
781 [RFC6761] Cheshire, S. and M. Krochmal, "Special-Use Domain Names",
782 RFC 6761, DOI 10.17487/RFC6761, February 2013,
783 .
785 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
786 Specifications and Registration Procedures", BCP 13,
787 RFC 6838, DOI 10.17487/RFC6838, January 2013,
788 .
790 [RFC6996] Mitchell, J., "Autonomous System (AS) Reservation for
791 Private Use", BCP 6, RFC 6996, DOI 10.17487/RFC6996, July
792 2013, .
794 [RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190,
795 RFC 7320, DOI 10.17487/RFC7320, July 2014,
796 .
798 Appendix A. JSend
800 According to [JSend], "JSend is a specification that lays down some
801 rules for how JSON responses from web servers should be formatted.
802 JSend focuses on application-level (as opposed to protocol- or
803 transport-level) messaging which makes it ideal for use in REST-style
804 applications and APIs."
806 A basic JSend-compliant response must contain a "status" key and
807 should contain "data", "message" and "code" keys dependent on the
808 status value. The following table lists the required and optional
809 keys.
811 +---------+-----------------+---------------+
812 | Type | Required keys | Optional keys |
813 +---------+-----------------+---------------+
814 | success | status, data | |
815 | fail | status, data | |
816 | error | status, message | code, data |
817 +---------+-----------------+---------------+
819 Table 1: Type and keys in JSend response
821 Author's Address
823 Markus Stubbig
824 Independent
825 Germany
827 Email: stubbig.ietf@gmail.com