--- 1/draft-ietf-regext-rdap-sorting-and-paging-09.txt 2020-04-14 04:14:11.007271177 -0700 +++ 2/draft-ietf-regext-rdap-sorting-and-paging-10.txt 2020-04-14 04:14:13.979347021 -0700 @@ -1,21 +1,21 @@ Registration Protocols Extensions M. Loffredo Internet-Draft M. Martinelli Intended status: Standards Track IIT-CNR/Registro.it -Expires: September 13, 2020 S. Hollenbeck +Expires: October 16, 2020 S. Hollenbeck Verisign Labs - March 12, 2020 + April 14, 2020 Registration Data Access Protocol (RDAP) Query Parameters for Result Sorting and Paging - draft-ietf-regext-rdap-sorting-and-paging-09 + draft-ietf-regext-rdap-sorting-and-paging-10 Abstract The Registration Data Access Protocol (RDAP) does not include core functionality for clients to provide sorting and paging parameters for control of large result sets. This omission can lead to unpredictable server processing of queries and client processing of responses. This unpredictability can be greatly reduced if clients can provide servers with their preferences for managing large responses. This document describes RDAP query extensions that allow @@ -30,21 +30,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on September 13, 2020. + This Internet-Draft will expire on October 16, 2020. Copyright Notice Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -70,21 +70,21 @@ 3. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 16 4. Implementation Considerations . . . . . . . . . . . . . . . . 17 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 17 5.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 17 5.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 18 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 9.1. Normative References . . . . . . . . . . . . . . . . . . 19 - 9.2. Informative References . . . . . . . . . . . . . . . . . 20 + 9.2. Informative References . . . . . . . . . . . . . . . . . 21 Appendix A. Approaches to Result Pagination . . . . . . . . . . 22 A.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 23 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 1. Introduction The availability of functionality for result sorting and paging provides benefits to both clients and servers in the implementation of RESTful services [REST]. These benefits include: @@ -232,23 +232,22 @@ o "links": "Link[]" (OPTIONAL) an array of links as described in RFC 8288 [RFC8288] containing the reference to the next page. In this specification, only the forward pagination is dealt because it is considered satisfactory in order to traverse the result set. Examples of additional references are to: the previous page, the first page, the last page. 2.1.1. RDAP Conformance Servers returning the "paging_metadata" element in their response - MUST include "paging_level_0" in the rdapConformance array as well as - servers returning the "sorting_metadata" element MUST include - "sorting_level_0". + MUST include "paging" in the rdapConformance array as well as servers + returning the "sorting_metadata" element MUST include "sorting". 2.2. "count" Parameter Currently, the RDAP protocol does not allow a client to determine the total number of the results in a query response when the result set is truncated. This is rather inefficient because the user cannot evaluate the query precision and, at the same time, cannot receive information that could be relevant. The "count" parameter provides additional functionality (Figure 1) @@ -266,21 +265,21 @@ falseValue = ("false" / "no" / "0") A trueValue means that the server MUST provide the total number of the objects in the "totalCount" field of the "paging_metadata" element (Figure 2). A falseValue means that the server MUST NOT provide this number. { "rdapConformance": [ "rdap_level_0", - "paging_level_0" + "paging" ], ... "paging_metadata": { "totalCount": 43 }, "domainSearchResults": [ ... ] } @@ -495,23 +494,23 @@ | Names | name | $.nameserverSearchResults[*].unicodeName | | erver | | | | | ipV4 | $.nameserverSearchResults[*].ipAddresses.v4 | | | | [0] | | | ipV6 | $.nameserverSearchResults[*].ipAddresses.v6 | | | | [0] | | | | | | Entit | handle | $.entitySearchResults[*].handle | | y | | | | | fn | $.entitySearchResults[*].vcardArray[1][?(@[ | - | | | 0]="fn")][3] | + | | | 0]=="fn")][3] | | | org | $.entitySearchResults[*].vcardArray[1][?(@[ | - | | | 0]="org")][3] | + | | | 0]=="org")][3] | | | voice | $.entitySearchResults[*].vcardArray[1][?(@[ | | | | 0]=="tel" && @[1].type=="voice")][3] | | | email | $.entitySearchResults[*].vcardArray[1][?(@[ | | | | 0]=="email")][3] | | | country | $.entitySearchResults[*].vcardArray[1][?(@[ | | | | 0]=="adr")][3][6] | | | cc | $.entitySearchResults[*].vcardArray[1][?(@[ | | | | 0]=="adr")][1].cc | | | city | $.entitySearchResults[*].vcardArray[1][?(@[ | | | | 0]=="adr")][3][3] | @@ -539,21 +538,21 @@ 2.3.2. Representing Sorting Links An RDAP server MAY use the "links" array of the "sorting_metadata" element to provide ready-made references [RFC8288] to the available sort criteria (Figure 4). Each link represents a reference to an alternate view of the results. { "rdapConformance": [ "rdap_level_0", - "sorting_level_0" + "sorting" ], ... "sorting_metadata": { "currentSort": "name", "availableSorts": [ { "property": "registrationDate", "jsonPath": "$.domainSearchResults[*] .events[?(@.eventAction==\"registration\")].eventDate", "default": false, @@ -569,22 +568,24 @@ }, { "value": "https://example.com/rdap/domains?name=*nr.com &sort=name", "rel": "alternate", "href": "https://example.com/rdap/domains?name=*nr.com &sort=registrationDate:d", "title": "Result Descending Sort Link", "type": "application/rdap+json" } - ], + ] + }, ... + ] }, "domainSearchResults": [ ... ] } Figure 4: Example of a "sorting_metadata" instance to implement result sorting 2.4. "cursor" Parameter @@ -618,21 +619,21 @@ 2.4.1. Representing Paging Links An RDAP server SHOULD use the "links" array of the "paging_metadata" element to provide a ready-made reference [RFC8288] to the next page of the result set (Figure 6). Examples of additional "rel" values a server MAY implements are "first", "last", "prev". { "rdapConformance": [ "rdap_level_0", - "paging_level_0" + "paging" ], ... "notices": [ { "title": "Search query limits", "type": "result set truncated due to excessive load", "description": [ "search results for domains are limited to 50" ] } @@ -829,34 +830,45 @@ [RFC7482] Newton, A. and S. Hollenbeck, "Registration Data Access Protocol (RDAP) Query Format", RFC 7482, DOI 10.17487/RFC7482, March 2015, . [RFC7483] Newton, A. and S. Hollenbeck, "JSON Responses for the Registration Data Access Protocol (RDAP)", RFC 7483, DOI 10.17487/RFC7483, March 2015, . + [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running + Code: The Implementation Status Section", BCP 205, + RFC 7942, DOI 10.17487/RFC7942, July 2016, + . + [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, . [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, . + [W3C.CR-xpath-31-20161213] + Robie, J., Dyck, M., and J. Spiegel, "XML Path Language + (XPath) 3.1", World Wide Web Consortium CR CR-xpath- + 31-20161213, December 2016, + . + 9.2. Informative References [CURSOR] Nimesh, R., "Paginating Real-Time Data with Keyset Pagination", July 2014, . [CURSOR-API1] facebook.com, "facebook for developers - Using the Graph API", July 2017, . @@ -885,36 +897,25 @@ [REST] Fredrich, T., "RESTful Service Best Practices, Recommendations for Creating Web Services", April 2012, . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . - [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running - Code: The Implementation Status Section", BCP 205, - RFC 7942, DOI 10.17487/RFC7942, July 2016, - . - [SEEK] EverSQL.com, "Faster Pagination in Mysql - Why Order By With Limit and Offset is Slow?", July 2017, . - [W3C.CR-xpath-31-20161213] - Robie, J., Dyck, M., and J. Spiegel, "XML Path Language - (XPath) 3.1", World Wide Web Consortium CR CR-xpath- - 31-20161213, December 2016, - . - Appendix A. Approaches to Result Pagination An RDAP query could return a response with hundreds, even thousands, of objects, especially when partial matching is used. For that reason, the cursor parameter addressing result pagination is defined to make responses easier to handle. Presently, the most popular methods to implement pagination in REST API are: offset pagination and keyset pagination. Both two pagination methods don't require the server to handle the result set @@ -1042,20 +1043,26 @@ 09: Updated the "Implementation Status" section to include APNIC implementation. Moved the "RDAP Conformance" section up in the document. Removed the "Paging Responses to POST Requests" section. Updated the "Acknowledgements" section. Removed unused references. In the "Sorting Properties Declaration" section: * clarified the logic of sorting on events; * corrected the JSON Path of the "lastChanged" sorting property; * provided a JSON Path example taking into account the vCard "pref" parameter. + 10: Corrected the JSON Paths of both "fn" and "org" sorting + properties in Table 2. Corrected JSON content in Figure 4. Moved + + [W3C.CR-xpath-31-20161213] and [RFC7942] to the "Normative + References". Changed the rdapConformance tags "sorting_level_0" + and "paging_level_0" to "sorting" and "paging" respectively. Authors' Addresses Mario Loffredo IIT-CNR/Registro.it Via Moruzzi,1 Pisa 56124 IT Email: mario.loffredo@iit.cnr.it