idnits 2.17.1 draft-ietf-regext-rdap-partial-response-12.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 17, 2020) is 1410 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7482 (Obsoleted by RFC 9082) ** Obsolete normative reference: RFC 7483 (Obsoleted by RFC 9083) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Registration Protocols Extensions M. Loffredo 3 Internet-Draft M. Martinelli 4 Intended status: Standards Track IIT-CNR/Registro.it 5 Expires: December 19, 2020 June 17, 2020 7 Registration Data Access Protocol (RDAP) Partial Response 8 draft-ietf-regext-rdap-partial-response-12 10 Abstract 12 The Registration Data Access Protocol (RDAP) does not include 13 capabilities to request partial responses. Servers will only return 14 full responses that include all of the information that a client is 15 authorized to receive. A partial response capability that limits the 16 amount of information returned, especially in the case of search 17 queries, could bring benefits to both clients and servers. This 18 document describes an RDAP query extension that allows clients to 19 specify their preference for obtaining a partial response. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 19, 2020. 38 Copyright Notice 40 Copyright (c) 2020 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 57 2. RDAP Path Segment Specification . . . . . . . . . . . . . . . 3 58 2.1. Subsetting Metadata . . . . . . . . . . . . . . . . . . . 3 59 2.1.1. RDAP Conformance . . . . . . . . . . . . . . . . . . 4 60 2.1.2. Representing Subsetting Links . . . . . . . . . . . . 4 61 3. Dealing with Relationships . . . . . . . . . . . . . . . . . 5 62 4. Basic Field Sets . . . . . . . . . . . . . . . . . . . . . . 6 63 5. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 7 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 65 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 66 7.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 8 67 7.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 71 9.2. Informative References . . . . . . . . . . . . . . . . . 10 72 Appendix A. Approaches to Partial Response Implementation . . . 11 73 A.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 12 74 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 75 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 78 1. Introduction 80 The use of partial responses in RESTful API [REST] design is very 81 common. The rationale is quite simple: instead of returning objects 82 in API responses with all data fields, only a subset of the fields in 83 each result object is returned. The benefit is obvious: fewer data 84 transferred over the network means less bandwidth usage, faster 85 server responses, less CPU time spent both on the server and the 86 client, and less memory usage on the client. 88 Several leading API providers [LINKEDIN] [FACEBOOK] [GOOGLE] 89 implement partial response features by providing an optional query 90 parameter through which clients identify the fields they wish to 91 receive. Support for partial responses is also considered a leading 92 principle by many best practice guidelines in REST API implementation 93 [REST-API1] [REST-API2] in order to improve performance, save on 94 bandwidth and possibly accelerate the overall interaction. In other 95 contexts, for example in digital libraries and bibliographic 96 catalogues, servers can respond according to different element sets 97 (i.e. "brief" to obtain a short response and "full" to obtain the 98 complete response). 100 Currently, RDAP does not provide a client with any way to request a 101 partial response. Servers can only provide the client with a full 102 response [RFC7483]. Servers cannot limit the amount of information 103 returned in a response based on a client's preferences, and this 104 creates inefficiencies. 106 The protocol described in this specification extends RDAP search 107 capabilities to enable partial responses through the provisioning of 108 pre-defined sets of fields that clients can submit to an RDAP service 109 by adding a new query parameter. The service is implemented using 110 the Hypertext Transfer Protocol (HTTP) [RFC7230] and the conventions 111 described in [RFC7480]. 113 1.1. Conventions Used in This Document 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in BCP 14 [RFC2119] 118 [RFC8174] when, and only when, they appear in all capitals, as shown 119 here. 121 2. RDAP Path Segment Specification 123 The path segment defined in this section is an OPTIONAL extension of 124 search path segments defined in [RFC7482]. This document defines an 125 RDAP query parameter, "fieldSet", whose value is a string identifying 126 a server-defined set of supported fields (Figure 1). 128 https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset 130 Figure 1: Example of RDAP search query reporting the "fieldSet" 131 parameter 133 This solution can be implemented by RDAP providers with less effort 134 than field selection and is easily requested by clients. The 135 considerations that have led to this solution are described in more 136 detail in Appendix A. 138 2.1. Subsetting Metadata 140 According to most advanced principles in REST design, collectively 141 known as HATEOAS (Hypermedia as the Engine of Application State) 142 [HATEOAS], a client entering a REST application through an initial 143 URI should use server-provided links to dynamically discover 144 available actions and access the resources it needs. In this way, 145 the client is not required to have prior knowledge of the service 146 and, consequently, to hard code the URIs of different resources. 147 This allows the server to make URI changes as the API evolves without 148 breaking clients. Definitively, a REST service should be as self- 149 descriptive as possible. 151 Therefore, servers implementing the query parameter described in this 152 specification SHOULD provide additional information in their 153 responses about the available field sets. Such information is 154 collected in a new data structure named "subsetting_metadata" 155 containing the following properties: 157 o "currentFieldSet": "String" (REQUIRED) either the value of the 158 "fieldSet" parameter as specified in the query string, or the 159 field set applied by default; 161 o "availableFieldSets": "AvailableFieldSet[]" (OPTIONAL) an array of 162 objects, with each element describing an available field set. 163 Members are: 165 * "name": "String" (REQUIRED) the field set name; 166 * "default": "Boolean" (REQUIRED) whether the field set is 167 applied by default; 168 * "description": "String" (OPTIONAL) a human-readable description 169 of the field set; 170 * "links": "Link[]" (OPTIONAL) an array of links as described in 171 [RFC8288] containing the query string that applies the field 172 set. 174 2.1.1. RDAP Conformance 176 Servers returning the "subsetting_metadata" section in their 177 responses MUST include "subsetting" in the rdapConformance array. 179 2.1.2. Representing Subsetting Links 181 An RDAP server MAY use the "links" array of the "subsetting_metadata" 182 element to provide ready-made references [RFC8288] to the available 183 field sets (Figure 2). The target URI in each link is the reference 184 to an alternative to the current view of results identified by the 185 context URI. 187 { 188 "rdapConformance": [ 189 "rdap_level_0", 190 "subsetting" 191 ], 192 ... 193 "subsetting_metadata": { 194 "currentFieldSet": "afieldset", 195 "availableFieldSets": [ 196 { 197 "name": "anotherfieldset", 198 "description": "Contains some fields", 199 "default": false, 200 "links": [ 201 { 202 "value": "https://example.com/rdap/domains?name=*nr.com 203 &fieldSet=afieldset", 204 "rel": "alternate", 205 "href": "https://example.com/rdap/domains?name=*nr.com 206 &fieldSet=anotherfieldset", 207 "title": "Result Subset Link", 208 "type": "application/rdap+json" 209 } 210 ] 211 }, 212 ... 213 ] 214 }, 215 ... 216 "domainSearchResults": [ 217 ... 218 ] 219 } 221 Figure 2: Example of a "subsetting_metadata" instance 223 3. Dealing with Relationships 225 Representation of second level objects within a field set produces 226 additional considerations. Since the topmost objects could be 227 returned according to different field sets, the same field sets could 228 be applied to their related objects. As a consequence, the response 229 could contain either no relationship or associated objects which are 230 in turn provided according to a field set. 232 4. Basic Field Sets 234 This section defines three basic field sets which servers MAY 235 implement to facilitate their interaction with clients: 237 o "id": the server provides only the key field, respectively: 238 "handle" for entities, "ldhName" for domains and nameservers. If 239 a returned domain or nameserver is an Internationalized Domain 240 Name (IDN) [RFC5890], then the "unicodeName" field MUST be 241 included in the response. This field set could be used when the 242 client wants to obtain a collection of object identifiers 243 (Figure 3); 245 o "brief": the field set contains the fields that can be included in 246 a "short" response. This field set could be used when the client 247 is asking for a subset of the full response which provides only 248 basic knowledge of each object; 250 o "full": the field set contains all of the information the server 251 can provide for a particular object. 253 The "objectClassName" field is implicitly included in each of the 254 above field sets. RDAP providers are RECOMMENDED to include a "self" 255 link in each field set. RDAP providers MAY also add any property 256 providing service information. 258 Fields included in the "brief" and "full" field sets MUST be returned 259 according to the user's access and authorization levels. 261 { 262 "rdapConformance": [ 263 "rdap_level_0", 264 "subsetting" 265 ], 266 ... 267 "domainSearchResults": [ 268 { 269 "objectClassName": "domain", 270 "ldhName": "example1.com", 271 "links": [ 272 { 273 "value": "https://example.com/rdap/domain/example1.com", 274 "rel": "self", 275 "href": "https://example.com/rdap/domain/example1.com", 276 "type": "application/rdap+json" 277 } 278 ] 279 }, 280 { 281 "objectClassName": "domain", 282 "ldhName": "example2.com", 283 "links": [ 284 { 285 "value": "https://example.com/rdap/domain/example2.com", 286 "rel": "self", 287 "href": "https://example.com/rdap/domain/example2.com", 288 "type": "application/rdap+json" 289 } 290 ] 291 }, 292 ... 293 ] 294 } 296 Figure 3: Example of RDAP response according to the "id" field set 298 5. Negative Answers 300 Each request including an unsupported field set SHOULD produce an 301 HTTP 400 (Bad Request) response code. Optionally, the response MAY 302 include additional information regarding the negative answer in the 303 HTTP entity body. 305 6. IANA Considerations 307 IANA is requested to register the following value in the RDAP 308 Extensions Registry: 310 Extension identifier: subsetting 311 Registry operator: Any 312 Published specification: This document. 313 Contact: IESG 314 Intended usage: This extension describes best practice for partial 315 response provisioning. 317 7. Implementation Status 319 NOTE: Please remove this section and the reference to RFC 7942 prior 320 to publication as an RFC. 322 This section records the status of known implementations of the 323 protocol defined by this specification at the time of posting of this 324 Internet-Draft, and is based on a proposal described in [RFC7942]. 325 The description of implementations in this section is intended to 326 assist the IETF in its decision processes in progressing drafts to 327 RFCs. Please note that the listing of any individual implementation 328 here does not imply endorsement by the IETF. Furthermore, no effort 329 has been spent to verify the information presented here that was 330 supplied by IETF contributors. This is not intended as, and must not 331 be construed to be, a catalog of available implementations or their 332 features. Readers are advised to note that other implementations may 333 exist. 335 According to RFC 7942, "this will allow reviewers and working groups 336 to assign due consideration to documents that have the benefit of 337 running code, which may serve as evidence of valuable experimentation 338 and feedback that have made the implemented protocols more mature. 339 It is up to the individual working groups to use this information as 340 they see fit". 342 7.1. IIT-CNR/Registro.it 344 Responsible Organization: Institute of Informatics and Telematics 345 of the National Research Council (IIT-CNR)/Registro.it 346 Location: https://rdap.pubtest.nic.it/ 347 Description: This implementation includes support for RDAP queries 348 using data from .it public test environment. 349 Level of Maturity: This is an "alpha" test implementation. 350 Coverage: This implementation includes all of the features 351 described in this specification. 352 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 354 7.2. APNIC 356 Responsible Organization: Asia-Pacific Network Information Centre 357 Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/partial- 358 response 359 Description: A proof-of-concept for RDAP mirroring. 360 Level of Maturity: This is a proof-of-concept implementation. 361 Coverage: This implementation includes all of the features 362 described in this specification. 363 Contact Information: Tom Harrison, tomh@apnic.net 365 8. Security Considerations 367 A search query typically requires more server resources (such as 368 memory, CPU cycles, and network bandwidth) when compared to a lookup 369 query. This increases the risk of server resource exhaustion and 370 subsequent denial of service due to abuse. This risk can be 371 mitigated by supporting the return of partial responses combined with 372 other strategies (e.g. restricting search functionality, limiting the 373 rate of search requests, and truncating and paging results). 375 Support for partial responses gives RDAP operators the ability to 376 implement data access control policies based on the HTTP 377 authentication mechanisms described in [RFC7481]. RDAP operators can 378 vary the information returned in RDAP responses based on a client's 379 access and authorization levels. For example: 381 o the list of fields for each set can differ based on the client's 382 access and authorization levels; 384 o the set of available field sets could be restricted based on the 385 client's access and authorization levels. 387 Servers can also define different result limits according to the 388 available field sets, so a more flexible truncation strategy can be 389 implemented. The new query parameter presented in this document 390 provides RDAP operators with a way to implement a server that reduces 391 inefficiency risks. 393 9. References 395 9.1. Normative References 397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 398 Requirement Levels", BCP 14, RFC 2119, 399 DOI 10.17487/RFC2119, March 1997, 400 . 402 [RFC5890] Klensin, J., "Internationalized Domain Names for 403 Applications (IDNA): Definitions and Document Framework", 404 RFC 5890, DOI 10.17487/RFC5890, August 2010, 405 . 407 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 408 Protocol (HTTP/1.1): Message Syntax and Routing", 409 RFC 7230, DOI 10.17487/RFC7230, June 2014, 410 . 412 [RFC7480] Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the 413 Registration Data Access Protocol (RDAP)", RFC 7480, 414 DOI 10.17487/RFC7480, March 2015, 415 . 417 [RFC7481] Hollenbeck, S. and N. Kong, "Security Services for the 418 Registration Data Access Protocol (RDAP)", RFC 7481, 419 DOI 10.17487/RFC7481, March 2015, 420 . 422 [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access 423 Protocol (RDAP) Query Format", RFC 7482, 424 DOI 10.17487/RFC7482, March 2015, 425 . 427 [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the 428 Registration Data Access Protocol (RDAP)", RFC 7483, 429 DOI 10.17487/RFC7483, March 2015, 430 . 432 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 433 Code: The Implementation Status Section", BCP 205, 434 RFC 7942, DOI 10.17487/RFC7942, July 2016, 435 . 437 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 438 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 439 May 2017, . 441 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 442 DOI 10.17487/RFC8288, October 2017, 443 . 445 9.2. Informative References 447 [CQL] Whitaker, G., "Catnap Query Language Reference", September 448 2017, . 451 [FACEBOOK] 452 facebook.com, "facebook for developers - Using the Graph 453 API", July 2017, . 456 [GOOGLE] google.com, "Making APIs Faster: Introducing Partial 457 Response and Partial Update", March 2010, 458 . 461 [HATEOAS] Jedrzejewski, B., "HATEOAS - a simple explanation", 2018, 462 . 465 [LINKEDIN] 466 linkedin.com, "Java One 2009: Building Consistent RESTful 467 APIs in a High Performance Environment", July 2009, 468 . 472 [REST] Fielding, R., "Architectural Styles and the Design of 473 Network-based Software Architectures", 2000, 474 . 477 [REST-API1] 478 Jobinesh, P., "RESTful Java Web Services - Second 479 Edition", September 2015. 481 [REST-API2] 482 Masse, M., "REST API Design Rulebook", October 2011. 484 Appendix A. Approaches to Partial Response Implementation 486 Looking at the implementation experiences described in Section 1, two 487 approaches to the implementation of partial response are observed: 489 o The client explicitly describes the data fields to be returned; 491 o The client describes a name identifying a server-defined set of 492 data fields. 494 The former is more flexible than the latter because clients can 495 specify all the data fields they need. However, it has some 496 drawbacks: 498 o Fields have to be declared according to a given syntax. This is a 499 simple task when the data structure of the object is flat, but it 500 is much more difficult when the object has a tree structure like 501 that of a JSON object. The presence of arrays and deep nested 502 objects complicate both the syntax definition of the query and, 503 consequently, the processing required on the server side; 505 o Clients need to recognize the returned data structure to avoid 506 cases when the requested fields are invalid; 508 o The request of some fields might not match the client's access and 509 authorization levels. Clients might request unauthorized fields 510 and servers should define a strategy for responding, such as 511 always returning an error response or returning a response that 512 ignores the unauthorized fields. 514 A.1. Specific Issues Raised by RDAP 516 In addition to those listed above, RDAP responses raise some specific 517 issues: 519 o Relevant entity object information is included in a jCard, but 520 such information cannot be easily selected because it is split 521 into the items of a jagged array; 523 o RDAP responses contain some properties providing service 524 information (e.g. rdapConformance, links, notices, remarks, etc.) 525 which are not normally selected but they are just as important. 526 They could be returned anyway but, in this case, the server would 527 provide unrequested data. 529 It is possible to address these issues. For example, the Catnap 530 Query Language [CQL] is a comprehensive expression language that can 531 be used to customize the JSON response of a RESTful web service. 532 Application of CQL to RDAP responses would explicitly identify the 533 output fields that would be acceptable when a few fields are 534 requested but it would become very complicated when processing a 535 larger number of fields. In the following, two CQL expressions for a 536 domain search query are shown (Figure 4). In the first, only 537 objectClassName and ldhName are requested. In the second, the fields 538 of a possible WHOIS-like response are listed. 540 https://example.com/rdap/domains?name=example*.com 541 &fields=domainSearchResults(objectClassName,ldhName) 543 https://example.com/rdap/domains?name=example*.com 544 &fields=domainSearchResults(objectClassName,ldhName, 545 unicodeName, 546 status, 547 events(eventAction,eventDate), 548 entities(objectClassName,handle,roles), 549 nameservers(objectClassName,ldhName)) 551 Figure 4: Examples of CQL expressions for a domain search query 553 The latter approach seems to facilitate RDAP interoperability. 554 Servers can define basic field sets which, if known to clients, can 555 increase the probability of obtaining a valid response. The usage of 556 field sets makes the query string be less complex. Moreover, the 557 definition of pre-defined sets of fields makes it easier to establish 558 result limits. 560 Finally, considering that there is no real need for RDAP users to 561 have the maximum flexibility in defining all the possible sets of 562 logically connected fields (e.g. users interested in domains usually 563 need to know the status, the creation date, and the expiry date of 564 each domain), the latter approach is preferred. 566 Acknowledgements 568 The authors would like to acknowledge Scott Hollenbeck, Tom Harrison, 569 Karl Heinz Wolf, Jasdip Singh and Patrick Mevzek for their 570 contribution to this document. 572 Change Log 574 00: Initial working group version ported from draft-loffredo-regext- 575 rdap-partial-response-03 576 01: Removed "FOR DISCUSSION" items. Changed the basic field sets 577 from REQUIRED to OPTIONAL. Removed the definition of fields 578 included in "brief" field set. Provided a more detailed 579 description of "subsetting_metadata" structure. Removed some 580 references. 581 02: Added the "Negative Answers" section. Changed "IANA 582 Considerations" section. 583 03: Added the "unicodeName" field in the id fieldSet when a returned 584 domain or nameserver is an IDN. Added RFC5890 to "Normative 585 References" section. 586 04: Recommended the RDAP providers to include a "self" link in any 587 field set other than "full". Updated "Acknowledgements" section. 589 05: Moved "Approaches to Partial Response Implementation" section to 590 the appendix. 591 06: Clarified the use of self links in "Basic Field Sets" section. 592 Added APNIC to the implementations of the "Implementation Status" 593 section. 594 07: Changed "only a subset is returned" to "only a subset of fields 595 in each result object is returned" in the "Introduction" section. 596 Moved the "RDAP Conformance" section up in the document. Updated 597 the "Acknowledgements" section. 598 08: Changed the rdapConformance tag "subsetting_level_0" to 599 "subsetting". Moved [RFC7942] to the "Normative References". 600 09: Corrected the "rdapConformance" content in Figure 3. 601 10: Corrected the JSON content in Figure 2. Clarified the meaning 602 of both context and target URIs in a result subset link defined in 603 Section 2.1.2. Updated the "Acknowledgements" section. 604 11: Minor pre-AD review edits. 605 12: Additional minor pre-AD review edits. 607 Authors' Addresses 609 Mario Loffredo 610 IIT-CNR/Registro.it 611 Via Moruzzi,1 612 Pisa 56124 613 IT 615 Email: mario.loffredo@iit.cnr.it 616 URI: http://www.iit.cnr.it 618 Maurizio Martinelli 619 IIT-CNR/Registro.it 620 Via Moruzzi,1 621 Pisa 56124 622 IT 624 Email: maurizio.martinelli@iit.cnr.it 625 URI: http://www.iit.cnr.it