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

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/