--- 1/draft-ietf-regext-rdap-sorting-and-paging-16.txt 2020-09-18 06:13:33.842458765 -0700 +++ 2/draft-ietf-regext-rdap-sorting-and-paging-17.txt 2020-09-18 06:13:33.898460182 -0700 @@ -1,21 +1,21 @@ Registration Protocols Extensions M. Loffredo Internet-Draft M. Martinelli Intended status: Standards Track IIT-CNR/Registro.it -Expires: February 21, 2021 S. Hollenbeck +Expires: March 22, 2021 S. Hollenbeck Verisign Labs - August 20, 2020 + September 18, 2020 Registration Data Access Protocol (RDAP) Query Parameters for Result Sorting and Paging - draft-ietf-regext-rdap-sorting-and-paging-16 + draft-ietf-regext-rdap-sorting-and-paging-17 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 February 21, 2021. + This Internet-Draft will expire on March 22, 2021. 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 @@ -63,37 +63,37 @@ 2.1.1. RDAP Conformance . . . . . . . . . . . . . . . . . . 6 2.2. "count" Parameter . . . . . . . . . . . . . . . . . . . . 6 2.3. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 7 2.3.1. Sorting Properties Declaration . . . . . . . . . . . 8 2.3.2. Representing Sorting Links . . . . . . . . . . . . . 14 2.4. "cursor" Parameter . . . . . . . . . . . . . . . . . . . 16 2.4.1. Representing Paging Links . . . . . . . . . . . . . . 16 3. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 17 4. Implementation Considerations . . . . . . . . . . . . . . . . 18 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 - 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 18 + 6. Implementation Status . . . . . . . . . . . . . . . . . . . . 19 6.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 19 6.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 19 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 - 8.2. Informative References . . . . . . . . . . . . . . . . . 21 - Appendix A. JSONPath operators . . . . . . . . . . . . . . . . . 22 + 8.2. Informative References . . . . . . . . . . . . . . . . . 22 + Appendix A. JSONPath operators . . . . . . . . . . . . . . . . . 23 Appendix B. Approaches to Result Pagination . . . . . . . . . . 24 B.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 25 Appendix C. Additional Implementation Notes . . . . . . . . . . 26 C.1. Sorting . . . . . . . . . . . . . . . . . . . . . . . . . 26 - C.2. Counting . . . . . . . . . . . . . . . . . . . . . . . . 26 - C.3. Paging . . . . . . . . . . . . . . . . . . . . . . . . . 26 + C.2. Counting . . . . . . . . . . . . . . . . . . . . . . . . 27 + C.3. Paging . . . . . . . . . . . . . . . . . . . . . . . . . 27 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 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: o reducing the server response bandwidth requirements; o improving server response time; o improving query precision and, consequently, obtaining more @@ -193,26 +193,27 @@ elements named "sorting_metadata" and "paging_metadata". The "sorting_metadata" element contains the following properties: o "currentSort": "String" (OPTIONAL) either the value of sort "parameter" as specified in the query string or the sort applied by default, if any; o "availableSorts": "AvailableSort[]" (OPTIONAL) an array of objects, with each element describing an available sort criterion. - Members are: + The AvailableSort object includes the following members: * "property": "String" (REQUIRED) the name that can be used by the client to request the sort criterion; * "default": "Boolean" (REQUIRED) whether the sort criterion is - applied by default; + applied by default. An RDAP server MUST define only one + default sorting property for each object class; * "jsonPath": "String" (OPTIONAL) the JSONPath of the RDAP field corresponding to the property; * "links": "Link[]" (OPTIONAL) an array of links as described in [RFC8288] containing the query string that applies the sort criterion. At least one of the "currentSort" and "availableSorts" properties MUST be present. The "paging_metadata" element contains the following fields: @@ -592,20 +593,23 @@ $.entitySearchResults[*].vcardArray[1][?(@[0]=="email" && @[1].pref=="1")][3] 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. + The "value", "rel" and "href" JSON values MUST be specified. All + other JSON values are OPTIONAL. + { "rdapConformance": [ "rdap_level_0", "sorting" ], ... "sorting_metadata": { "currentSort": "name", "availableSorts": [ { @@ -726,21 +730,34 @@ parameter SHOULD produce an HTTP 400 (Bad Request) response code. The same response SHOULD be returned in the following cases: o If in both single and multi sort the client provides an unsupported value for the "sort" parameter, as well as a value related to an object property not included in the response; o If the client submits an invalid value for the "cursor" parameter. Optionally, the response MAY include additional information regarding - the negative answer in the HTTP entity body. + either the supported sorting properties or the correct cursor values + in the HTTP entity body (Figure 7). + +{ + "errorCode": 400, + "title": "Domain sorting property 'unknownproperty' is not valid", + "description": [ + "Supported domain sorting properties are: 'aproperty', 'anotherproperty'." + ] + +} + + Figure 7: Example of RDAP error response due to an invalid domain + sorting property included in the request 4. Implementation Considerations Implementation of the new parameters is technically feasible, as operators for counting, sorting and paging are currently supported by the major relational database management systems. Similar operators are completely or partially supported by the most well-known NoSQL databases (e.g. MongoDB, CouchDB, HBase, Cassandra, Hadoop). Additional implementation notes are included in Appendix C. @@ -813,26 +830,26 @@ Contact Information: Tom Harrison, tomh@apnic.net 7. Security Considerations Security services for the operations specified in this document are described in [RFC7481]. A search query typically requires more server resources (such as memory, CPU cycles, and network bandwidth) when compared to a lookup query. This increases the risk of server resource exhaustion and - subsequent denial of service due to abuse. This risk can be - mitigated by either restricting search functionality or limiting the - rate of search requests. Servers can also reduce their load by - truncating the results in a response. However, this last security - policy can result in a higher inefficiency if the RDAP server does - not provide any functionality to return the truncated results. + subsequent denial of service. This risk can be mitigated by either + restricting search functionality or limiting the rate of search + requests. Servers can also reduce their load by truncating the + results in a response. However, this last security policy can result + in a higher inefficiency if the RDAP server does not provide any + functionality to return the truncated results. The new parameters presented in this document provide RDAP operators with a way to implement a server that reduces inefficiency risks. The "count" parameter gives the client the ability to evaluate the completeness of a response. The "sort" parameter allows the client to obtain the most relevant information at the beginning of the result set. This can reduce the number of unnecessary search requests. Finally, the "cursor" parameter enables the user to scroll the result set by submitting a sequence of sustainable queries within server-acceptable limits. @@ -939,24 +956,24 @@ explanation/>. [OData-Part1] Pizzo, M., Handl, R., and M. Zurmuehl, "OData Version 4.0. Part 1: Protocol Plus Errata 03", June 2016, . - [REST] Fredrich, T., "RESTful Service Best Practices, - Recommendations for Creating Web Services", April 2012, - . + [REST] Fielding, R., "Architectural Styles and the Design of + Network-based Software Architectures", 2000, + . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [SEEK] EverSQL.com, "Faster Pagination in Mysql - Why Order By With Limit and Offset is Slow?", July 2017, . @@ -1225,20 +1243,43 @@ 14: Additionl minor pre-AD review edits. 15: In section ""sort" Parameter" added a paragraph providing conversions of IP addresses into their numerical representations. In section "Sorting Properties Declaration" rearranged Table 2 in a list to make the content more readable. Other minor edits due to AD review. 16: In section "Introduction" replaced "... large result set that could be truncated ..." with "... large result set that is often truncated ..." as suggested by Gen-ART reviewer. Added Appendix C. + 17: Edits made: + + * in the "Sorting and Paging Metadata" section: + + + replaced "Members are:" with "The AvailableSort object + includes the following members:"; + + clarified that an RDAP server MUST define only one default + sorting property for each object class; + * in the "Negative Answers" section: + + + replaced the phrase "the response MAY include additional + information regarding the negative answer" with the phrase + "the response MAY include additional information regarding + either the supported sorting properties or the correct + cursor value"; + + added a new example; + * clarified the required members of a Link object in the + "Representing Sorting Links" section; + * corrected the [REST] reference in the "Informative References" + section; + * replaced the phrase "and subsequent denial of service due to + abuse" with the phrase "and subsequent denial of service" in + "Security Considerations" section. Authors' Addresses Mario Loffredo IIT-CNR/Registro.it Via Moruzzi,1 Pisa 56124 IT Email: mario.loffredo@iit.cnr.it