draft-ietf-regext-rdap-partial-response-12.txt   draft-ietf-regext-rdap-partial-response-13.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: December 19, 2020 June 17, 2020 Expires: January 30, 2021 July 29, 2020
Registration Data Access Protocol (RDAP) Partial Response Registration Data Access Protocol (RDAP) Partial Response
draft-ietf-regext-rdap-partial-response-12 draft-ietf-regext-rdap-partial-response-13
Abstract Abstract
The Registration Data Access Protocol (RDAP) does not include The Registration Data Access Protocol (RDAP) does not include
capabilities to request partial responses. Servers will only return capabilities to request partial responses. Servers will only return
full responses that include all of the information that a client is full responses that include all of the information that a client is
authorized to receive. A partial response capability that limits the authorized to receive. A partial response capability that limits the
amount of information returned, especially in the case of search amount of information returned, especially in the case of search
queries, could bring benefits to both clients and servers. This queries, could bring benefits to both clients and servers. This
document describes an RDAP query extension that allows clients to document describes an RDAP query extension that allows clients to
skipping to change at page 1, line 37 skipping to change at page 1, line 37
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 December 19, 2020. This Internet-Draft will expire on January 30, 2021.
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 28 skipping to change at page 2, line 28
5. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 7 5. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 7
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8
7.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 8 7.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 8
7.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 9 7.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
9.1. Normative References . . . . . . . . . . . . . . . . . . 9 9.1. Normative References . . . . . . . . . . . . . . . . . . 9
9.2. Informative References . . . . . . . . . . . . . . . . . 10 9.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Approaches to Partial Response Implementation . . . 11 Appendix A. Approaches to Partial Response Implementation . . . 11
A.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 12 A.1. Specific Issues Raised by RDAP . . . . . . . . . . . . . 11
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
The use of partial responses in RESTful API [REST] design is very The use of partial responses in RESTful API [REST] design is very
common. The rationale is quite simple: instead of returning objects common. The rationale is quite simple: instead of returning objects
in API responses with all data fields, only a subset of the fields in in API responses with all data fields, only a subset of the fields in
each result object is returned. The benefit is obvious: fewer data each result object is returned. The benefit is obvious: fewer data
transferred over the network means less bandwidth usage, faster transferred over the network means less bandwidth usage, faster
server responses, less CPU time spent both on the server and the server responses, less CPU time spent both on the server and the
client, and less memory usage on the client. client, and less memory usage on the client.
Several leading API providers [LINKEDIN] [FACEBOOK] [GOOGLE]
implement partial response features by providing an optional query
parameter through which clients identify the fields they wish to
receive. Support for partial responses is also considered a leading
principle by many best practice guidelines in REST API implementation
[REST-API1] [REST-API2] in order to improve performance, save on
bandwidth and possibly accelerate the overall interaction. In other
contexts, for example in digital libraries and bibliographic
catalogues, servers can respond according to different element sets
(i.e. "brief" to obtain a short response and "full" to obtain the
complete response).
Currently, RDAP does not provide a client with any way to request a Currently, RDAP does not provide a client with any way to request a
partial response. Servers can only provide the client with a full partial response. Servers can only provide the client with a full
response [RFC7483]. Servers cannot limit the amount of information response [RFC7483]. Servers cannot limit the amount of information
returned in a response based on a client's preferences, and this returned in a response based on a client's preferences, and this
creates inefficiencies. creates inefficiencies.
The protocol described in this specification extends RDAP search The protocol described in this specification extends RDAP search
capabilities to enable partial responses through the provisioning of capabilities to enable partial responses through the provisioning of
pre-defined sets of fields that clients can submit to an RDAP service pre-defined sets of fields that clients can submit to an RDAP service
by adding a new query parameter. The service is implemented using by adding a new query parameter. The service is implemented using
the Hypertext Transfer Protocol (HTTP) [RFC7230] and the conventions the Hypertext Transfer Protocol (HTTP) [RFC7230] and the conventions
described in [RFC7480]. described in [RFC7480].
1.1. Conventions Used in This Document 1.1. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in BCP 14 [RFC2119] "OPTIONAL" in this document are to be interpreted as described in BCP
[RFC8174] when, and only when, they appear in all capitals, as shown 14 [RFC2119] [RFC8174] when, and only when, they appear in all
here. capitals, as shown here.
2. RDAP Path Segment Specification 2. RDAP Path Segment Specification
The path segment defined in this section is an OPTIONAL extension of The path segment defined in this section is an OPTIONAL extension of
search path segments defined in [RFC7482]. This document defines an search path segments defined in [RFC7482]. This document defines an
RDAP query parameter, "fieldSet", whose value is a string identifying RDAP query parameter, "fieldSet", whose value is a non-empty string
a server-defined set of supported fields (Figure 1). identifying a server-defined set of fields returned in place of the
full response (Figure 1). The field sets supported by a server are
usually described in out-of-band documents (e.g. RDAP profile)
together with other features. Moreover, this document defines in
Section 2.1 an in-band mechanism by means of which servers can
provide clients with a basic information about the supported field
sets.
https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset
Figure 1: Example of RDAP search query reporting the "fieldSet" Figure 1: Example of RDAP search query reporting the "fieldSet"
parameter parameter
This solution can be implemented by RDAP providers with less effort This solution can be implemented by RDAP providers with less effort
than field selection and is easily requested by clients. The than field selection and is easily requested by clients. The
considerations that have led to this solution are described in more considerations that have led to this solution are described in more
detail in Appendix A. detail in Appendix A.
skipping to change at page 6, line 10 skipping to change at page 6, line 10
returned according to different field sets, the same field sets could returned according to different field sets, the same field sets could
be applied to their related objects. As a consequence, the response be applied to their related objects. As a consequence, the response
could contain either no relationship or associated objects which are could contain either no relationship or associated objects which are
in turn provided according to a field set. in turn provided according to a field set.
4. Basic Field Sets 4. Basic Field Sets
This section defines three basic field sets which servers MAY This section defines three basic field sets which servers MAY
implement to facilitate their interaction with clients: implement to facilitate their interaction with clients:
o "id": the server provides only the key field, respectively: o "id": the server provides only the key field: "handle" for
"handle" for entities, "ldhName" for domains and nameservers. If entities, "ldhName" for domains and nameservers. If a returned
a returned domain or nameserver is an Internationalized Domain domain or nameserver is an Internationalized Domain Name (IDN)
Name (IDN) [RFC5890], then the "unicodeName" field MUST be [RFC5890], then the "unicodeName" field MUST be included in the
included in the response. This field set could be used when the response. This field set could be used when the client wants to
client wants to obtain a collection of object identifiers obtain a collection of object identifiers (Figure 3);
(Figure 3);
o "brief": the field set contains the fields that can be included in o "brief": the field set contains the fields that can be included in
a "short" response. This field set could be used when the client a "short" response. This field set could be used when the client
is asking for a subset of the full response which provides only is asking for a subset of the full response which provides only
basic knowledge of each object; basic knowledge of each object;
o "full": the field set contains all of the information the server o "full": the field set contains all of the information the server
can provide for a particular object. can provide for a particular object.
The "objectClassName" field is implicitly included in each of the The "objectClassName" field is implicitly included in each of the
above field sets. RDAP providers are RECOMMENDED to include a "self" above field sets. RDAP providers SHOULD include a "self" link in
link in each field set. RDAP providers MAY also add any property each field set. RDAP providers MAY also add any property providing
providing service information. service information.
Fields included in the "brief" and "full" field sets MUST be returned Fields included in the "brief" and "full" field set responses MUST
according to the user's access and authorization levels. take into account the user's access and authorization levels.
{ {
"rdapConformance": [ "rdapConformance": [
"rdap_level_0", "rdap_level_0",
"subsetting" "subsetting"
], ],
... ...
"domainSearchResults": [ "domainSearchResults": [
{ {
"objectClassName": "domain", "objectClassName": "domain",
skipping to change at page 7, line 44 skipping to change at page 7, line 44
] ]
}, },
... ...
] ]
} }
Figure 3: Example of RDAP response according to the "id" field set Figure 3: Example of RDAP response according to the "id" field set
5. Negative Answers 5. Negative Answers
Each request including an unsupported field set SHOULD produce an Each request including an empty or unsupported "fieldSet" value MUST
HTTP 400 (Bad Request) response code. Optionally, the response MAY produce an HTTP 400 (Bad Request) response code. Optionally, the
include additional information regarding the negative answer in the response MAY include additional information regarding the negative
HTTP entity body. answer in the HTTP entity body.
6. IANA Considerations 6. IANA Considerations
IANA is requested to register the following value in the RDAP IANA is requested to register the following value in the RDAP
Extensions Registry: Extensions Registry:
Extension identifier: subsetting Extension identifier: subsetting
Registry operator: Any Registry operator: Any
Published specification: This document. Published specification: This document.
Contact: IESG <iesg@ietf.org> Contact: IETF <iesg@ietf.org>
Intended usage: This extension describes best practice for partial Intended usage: This extension describes best practice for partial
response provisioning. response provisioning.
7. Implementation Status 7. Implementation Status
NOTE: Please remove this section and the reference to RFC 7942 prior NOTE: Please remove this section and the reference to RFC 7942 prior
to publication as an RFC. to publication as an RFC.
This section records the status of known implementations of the This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this protocol defined by this specification at the time of posting of this
skipping to change at page 11, line 5 skipping to change at page 11, line 5
[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>.
9.2. Informative References 9.2. Informative References
[CQL] Whitaker, G., "Catnap Query Language Reference", September [CQL] Whitaker, G., "Catnap Query Language Reference", September
2017, <https://github.com/gregwhitaker/catnap/wiki/Catnap- 2017, <https://github.com/gregwhitaker/catnap/wiki/Catnap-
Query-Language-Reference>. Query-Language-Reference>.
[FACEBOOK]
facebook.com, "facebook for developers - Using the Graph
API", July 2017, <https://developers.facebook.com/docs/
graph-api/using-graph-api>.
[GOOGLE] google.com, "Making APIs Faster: Introducing Partial
Response and Partial Update", March 2010,
<http://googlecode.blogspot.it/2010/03/making-apis-faster-
introducing-partial.html>.
[HATEOAS] Jedrzejewski, B., "HATEOAS - a simple explanation", 2018, [HATEOAS] Jedrzejewski, B., "HATEOAS - a simple explanation", 2018,
<https://www.e4developer.com/2018/02/16/hateoas-simple- <https://www.e4developer.com/2018/02/16/hateoas-simple-
explanation/>. explanation/>.
[LINKEDIN]
linkedin.com, "Java One 2009: Building Consistent RESTful
APIs in a High Performance Environment", July 2009,
<https://blog.linkedin.com/2009/07/08/brandon-duncan-java-
one-building-consistent-restful-apis-in-a-high-
performance-environment>.
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000, Network-based Software Architectures", 2000,
<http://www.restapitutorial.com/media/ <http://www.restapitutorial.com/media/
RESTful_Best_Practices-v1_1.pdf>. RESTful_Best_Practices-v1_1.pdf>.
[REST-API1]
Jobinesh, P., "RESTful Java Web Services - Second
Edition", September 2015.
[REST-API2]
Masse, M., "REST API Design Rulebook", October 2011.
Appendix A. Approaches to Partial Response Implementation Appendix A. Approaches to Partial Response Implementation
Looking at the implementation experiences described in Section 1, two Looking at the implementation experiences of partial response, two
approaches to the implementation of partial response are observed: approaches are observed:
o The client explicitly describes the data fields to be returned; o The client explicitly describes the data fields to be returned;
o The client describes a name identifying a server-defined set of o The client describes a name identifying a server-defined set of
data fields. data fields.
The former is more flexible than the latter because clients can The former is more flexible than the latter because clients can
specify all the data fields they need. However, it has some specify all the data fields they need. However, it has some
drawbacks: drawbacks:
skipping to change at page 14, line 22 skipping to change at page 13, line 44
Moved the "RDAP Conformance" section up in the document. Updated Moved the "RDAP Conformance" section up in the document. Updated
the "Acknowledgements" section. the "Acknowledgements" section.
08: Changed the rdapConformance tag "subsetting_level_0" to 08: Changed the rdapConformance tag "subsetting_level_0" to
"subsetting". Moved [RFC7942] to the "Normative References". "subsetting". Moved [RFC7942] to the "Normative References".
09: Corrected the "rdapConformance" content in Figure 3. 09: Corrected the "rdapConformance" content in Figure 3.
10: Corrected the JSON content in Figure 2. Clarified the meaning 10: Corrected the JSON content in Figure 2. Clarified the meaning
of both context and target URIs in a result subset link defined in of both context and target URIs in a result subset link defined in
Section 2.1.2. Updated the "Acknowledgements" section. Section 2.1.2. Updated the "Acknowledgements" section.
11: Minor pre-AD review edits. 11: Minor pre-AD review edits.
12: Additional minor pre-AD review edits. 12: Additional minor pre-AD review edits.
13: Edits due to Gen-ART review: in the first paragraph of Section 2
clarified how field sets are defined by a server, in the first
sentence of Section 5 replaced SHOULD with MUST. Other minor
edits due to AD review.
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. 
65 lines changed or deleted 38 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/