draft-ietf-regext-rdap-partial-response-15.txt   draft-ietf-regext-rdap-partial-response-16.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: March 17, 2021 September 13, 2020 Expires: March 27, 2021 September 23, 2020
Registration Data Access Protocol (RDAP) Partial Response Registration Data Access Protocol (RDAP) Partial Response
draft-ietf-regext-rdap-partial-response-15 draft-ietf-regext-rdap-partial-response-16
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 March 17, 2021. This Internet-Draft will expire on March 27, 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 3, line 22 skipping to change at page 3, line 22
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown 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 non-empty string RDAP query parameter, "fieldSet", whose value is a non-empty string
identifying a server-defined set of fields returned in place of the identifying a server-defined set of fields returned in place of the
full response (Figure 1). The field sets supported by a server are full response. The field sets supported by a server are usually
usually described in out-of-band documents (e.g., RDAP profile) described in out-of-band documents (e.g., RDAP profile) together with
together with other features. Moreover, this document defines in other features. Moreover, this document defines in Section 2.1 an
Section 2.1 an in-band mechanism by means of which servers can in-band mechanism by means of which servers can provide clients with
provide clients with a basic information about the supported field a basic information about the supported field sets.
sets.
https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset The following is an example of an RDAP query including the "fieldSet"
parameter:
Figure 1: Example of RDAP search query reporting the "fieldSet" https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset
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.
2.1. Subsetting Metadata 2.1. Subsetting Metadata
According to most advanced principles in REST design, collectively According to most advanced principles in REST design, collectively
known as HATEOAS (Hypermedia as the Engine of Application State) known as HATEOAS (Hypermedia as the Engine of Application State)
skipping to change at page 4, line 38 skipping to change at page 4, line 38
2.1.1. RDAP Conformance 2.1.1. RDAP Conformance
Servers returning the "subsetting_metadata" section in their Servers returning the "subsetting_metadata" section in their
responses MUST include "subsetting" in the rdapConformance array. responses MUST include "subsetting" in the rdapConformance array.
2.1.2. Representing Subsetting Links 2.1.2. Representing Subsetting Links
An RDAP server MAY use the "links" array of the "subsetting_metadata" An RDAP server MAY use the "links" array of the "subsetting_metadata"
element to provide ready-made references [RFC8288] to the available element to provide ready-made references [RFC8288] to the available
field sets (Figure 2). The target URI in each link is the reference field sets (Figure 1). The target URI in each link is the reference
to an alternative to the current view of results identified by the to an alternative to the current view of results identified by the
context URI. context URI.
The "value", "rel" and "href" JSON values MUST be specified. All The "value", "rel" and "href" JSON values MUST be specified. All
other JSON values are OPTIONAL. other JSON values are OPTIONAL.
{ {
"rdapConformance": [ "rdapConformance": [
"rdap_level_0", "rdap_level_0",
"subsetting" "subsetting"
skipping to change at page 5, line 20 skipping to change at page 5, line 20
... ...
"subsetting_metadata": { "subsetting_metadata": {
"currentFieldSet": "afieldset", "currentFieldSet": "afieldset",
"availableFieldSets": [ "availableFieldSets": [
{ {
"name": "anotherfieldset", "name": "anotherfieldset",
"description": "Contains some fields", "description": "Contains some fields",
"default": false, "default": false,
"links": [ "links": [
{ {
"value": "https://example.com/rdap/domains?name=*nr.com "value": "https://example.com/rdap/domains?name=example*.com
&fieldSet=afieldset", &fieldSet=afieldset",
"rel": "alternate", "rel": "alternate",
"href": "https://example.com/rdap/domains?name=*nr.com "href": "https://example.com/rdap/domains?name=example*.com
&fieldSet=anotherfieldset", &fieldSet=anotherfieldset",
"title": "Result Subset Link", "title": "Result Subset Link",
"type": "application/rdap+json" "type": "application/rdap+json"
} }
] ]
}, },
... ...
] ]
}, },
... ...
"domainSearchResults": [ "domainSearchResults": [
... ...
] ]
} }
Figure 2: Example of a "subsetting_metadata" instance Figure 1: Example of a "subsetting_metadata" instance
3. Dealing with Relationships 3. Dealing with Relationships
Representation of second level objects within a field set produces Representation of second level objects within a field set produces
additional considerations. Since the representation of the topmost additional considerations. Since the representation of the topmost
returned objects will vary according to the field set in use, the returned objects will vary according to the field set in use, the
response may contain no relationships (e.g., for an abbreviated field response may contain no relationships (e.g., for an abbreviated field
set) or may contain associated objects as in a normal RDAP query set) or may contain associated objects as in a normal RDAP query
response. Each field set can indicate the format of the additional response. Each field set can indicate the format of the additional
objects to be returned, in the same manner that the format of the objects to be returned, in the same manner that the format of the
skipping to change at page 6, line 16 skipping to change at page 6, line 16
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: "handle" for o "id": the server provides only the key field: "handle" for
entities, "ldhName" for domains and nameservers. If a returned entities, "ldhName" for domains and nameservers. If a returned
domain or nameserver is an Internationalized Domain Name (IDN) domain or nameserver is an Internationalized Domain Name (IDN)
[RFC5890], then the "unicodeName" field MUST additionally be [RFC5890], then the "unicodeName" field MUST additionally be
included in the response. This field set could be used when the included in the response. This field set could be used when the
client wants to obtain a collection of object identifiers client wants to obtain a collection of object identifiers
(Figure 3); (Figure 2);
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
skipping to change at page 7, line 40 skipping to change at page 7, line 40
"rel": "self", "rel": "self",
"href": "https://example.com/rdap/domain/example2.com", "href": "https://example.com/rdap/domain/example2.com",
"type": "application/rdap+json" "type": "application/rdap+json"
} }
] ]
}, },
... ...
] ]
} }
Figure 3: Example of RDAP response according to the "id" field set Figure 2: Example of RDAP response according to the "id" field set
5. Negative Answers 5. Negative Answers
Each request including an empty or unsupported "fieldSet" value MUST Each request including an empty or unsupported "fieldSet" value MUST
produce an HTTP 400 (Bad Request) response code. Optionally, the produce an HTTP 400 (Bad Request) response code. Optionally, the
response MAY include additional information regarding the supported response MAY include additional information regarding the supported
field sets in the HTTP entity body (Figure 4). field sets in the HTTP entity body (Figure 3).
{ {
"errorCode": 400, "errorCode": 400,
"title": "Field set 'unknownfieldset' is not valid", "title": "Field set 'unknownfieldset' is not valid",
"description": [ "description": [
"Supported field sets are: 'afieldset', 'anotherfieldset'." "Supported field sets are: 'afieldset', 'anotherfieldset'."
] ]
} }
Figure 4: Example of RDAP error response due to an invalid field set Figure 3: Example of RDAP error response due to an invalid field set
included in the request included in the request
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.
skipping to change at page 11, line 33 skipping to change at page 11, line 33
[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.ics.uci.edu/~fielding/pubs/dissertation/ <http://www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>. fielding_dissertation.pdf>.
Appendix A. Approaches to Partial Response Implementation Appendix A. Approaches to Partial Response Implementation
Looking at the implementation experiences of partial response offered Looking at the implementation experiences of partial response offered
by data providers on the web, two approaches are observed: by data providers on the web, two 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:
o Fields have to be declared according to a given syntax. This is a o fields have to be declared according to a given syntax. This is a
simple task when the data structure of the object is flat, but it simple task when the data structure of the object is flat, but it
is much more difficult when the object has a tree structure like is much more difficult when the object has a tree structure like
that of a JSON object. The presence of arrays and deep nested that of a JSON object. The presence of arrays and deep nested
objects complicate both the syntax definition of the query and, objects complicate both the syntax definition of the query and,
consequently, the processing required on the server side; consequently, the processing required on the server side;
o Clients need to recognize the returned data structure to avoid o clients need to recognize the returned data structure to avoid
cases when the requested fields are invalid; cases when the requested fields are invalid;
o The request of some fields might not match the client's access and o the request of some fields might not match the client's access and
authorization levels. Clients might request unauthorized fields authorization levels. Clients might request unauthorized fields
and servers have to define a strategy for responding, such as and servers have to define a strategy for responding, such as
always returning an error response or returning a response that always returning an error response or returning a response that
ignores the unauthorized fields. ignores the unauthorized fields.
A.1. Specific Issues Raised by RDAP A.1. Specific Issues Raised by RDAP
In addition to those listed above, RDAP responses raise some specific In addition to those listed above, RDAP responses raise some specific
issues: issues:
o Relevant entity object information is included in a jCard, but o relevant entity object information is included in a jCard, but
such information cannot be easily selected because it is split such information cannot be easily selected because it is split
into the items of a jagged array; into the items of a jagged array;
o RDAP responses contain some properties providing service o RDAP responses contain some properties providing service
information (e.g. rdapConformance, links, notices, remarks, etc.) information (e.g. rdapConformance, links, notices, remarks, etc.)
which are not normally selected but they are just as important. which are not normally selected but they are just as important.
They could be returned anyway but, in this case, the server would They could be returned anyway but, in this case, the server would
provide unrequested data. provide unrequested data.
It is possible to address these issues. For example, the Catnap It is possible to address these issues. For example, the Catnap
Query Language [CQL] is a comprehensive expression language that can Query Language [CQL] is a comprehensive expression language that can
be used to customize the JSON response of a RESTful web service. be used to customize the JSON response of a RESTful web service.
Application of CQL to RDAP responses would explicitly identify the Application of CQL to RDAP responses would explicitly identify the
output fields that would be acceptable when a few fields are output fields that would be acceptable when a few fields are
requested but it would become very complicated when processing a requested but it would become very complicated when processing a
larger number of fields. In the following, two CQL expressions for a larger number of fields. In the following, two CQL expressions for a
domain search query are shown (Figure 5). In the first, only domain search query are shown (Figure 4). In the first, only
objectClassName and ldhName are requested. In the second, the fields objectClassName and ldhName are requested. In the second, the fields
of a possible WHOIS-like response are listed. of a possible WHOIS-like response are listed.
https://example.com/rdap/domains?name=example*.com https://example.com/rdap/domains?name=example*.com
&fields=domainSearchResults(objectClassName,ldhName) &fields=domainSearchResults(objectClassName,ldhName)
https://example.com/rdap/domains?name=example*.com https://example.com/rdap/domains?name=example*.com
&fields=domainSearchResults(objectClassName,ldhName, &fields=domainSearchResults(objectClassName,ldhName,
unicodeName, unicodeName,
status, status,
events(eventAction,eventDate), events(eventAction,eventDate),
entities(objectClassName,handle,roles), entities(objectClassName,handle,roles),
nameservers(objectClassName,ldhName)) nameservers(objectClassName,ldhName))
Figure 5: Examples of CQL expressions for a domain search query Figure 4: Examples of CQL expressions for a domain search query
The field set approach seems to facilitate RDAP interoperability. The field set approach seems to facilitate RDAP interoperability.
Servers can define basic field sets which, if known to clients, can Servers can define basic field sets which, if known to clients, can
increase the probability of obtaining a valid response. The usage of increase the probability of obtaining a valid response. The usage of
field sets makes the query string be less complex. Moreover, the field sets makes the query string be less complex. Moreover, the
definition of pre-defined sets of fields makes it easier to establish definition of pre-defined sets of fields makes it easier to establish
result limits. result limits.
Finally, considering that there is no real need for RDAP users to Finally, considering that there is no real need for RDAP users to
have the maximum flexibility in defining all the possible sets of have the maximum flexibility in defining all the possible sets of
skipping to change at page 13, line 49 skipping to change at page 13, line 49
the appendix. the appendix.
06: Clarified the use of self links in "Basic Field Sets" section. 06: Clarified the use of self links in "Basic Field Sets" section.
Added APNIC to the implementations of the "Implementation Status" Added APNIC to the implementations of the "Implementation Status"
section. section.
07: Changed "only a subset is returned" to "only a subset of fields 07: Changed "only a subset is returned" to "only a subset of fields
in each result object is returned" in the "Introduction" section. in each result object is returned" in the "Introduction" section.
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 2.
10: Corrected the JSON content in Figure 2. Clarified the meaning 10: Corrected the JSON content in Figure 1. 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 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 clarified how field sets are defined by a server, in the first
sentence of Section 5 replaced SHOULD with MUST. Other minor sentence of Section 5 replaced SHOULD with MUST. Other minor
edits due to AD review. edits due to AD review.
14: Edits due to IESG review: 14: Edits due to IESG review:
* replaced "fewer data transferred" with "less data transferred" * replaced "fewer data transferred" with "less data transferred"
in the "Introduction" section; in the "Introduction" section;
* in the "Subsetting Metadata" section;: * in the "Subsetting Metadata" section:
+ replaced the phrase "collected in a new data structure" with + replaced the phrase "collected in a new data structure" with
the phrase "collected in a new JSON data structure"; the phrase "collected in a new JSON data structure";
+ replaced "Members are:" with "The AvailableFieldSet object + replaced "Members are:" with "The AvailableFieldSet object
includes the following members:"; includes the following members:";
+ clarified that an RDAP server MUST define only one default + clarified that an RDAP server MUST define only one default
field set; field set;
* clarified the required members of a Link object in the * clarified the required members of a Link object in the
"Subsetting Links" section; "Representing Subsetting Links" section;
* rewritten the "Dealing with Relationships" section; * rewritten the "Dealing with Relationships" section;
* in the "Basic Field Sets" section: * in the "Basic Field Sets" section:
+ replaced the phrase "include a 'self' link in each field + replaced the phrase "include a 'self' link in each field
set" with the phrase "include a 'links' field indicating the set" with the phrase "include a 'links' field indicating the
'self' link relationship"; 'self' link relationship";
+ replaced the phrase "'unicodeName' field MUST be included" + replaced the phrase "'unicodeName' field MUST be included"
with the phrase "'unicodeName' field MUST additionally be with the phrase "'unicodeName' field MUST additionally be
included"; included";
* in the "Negative Answers" section: * in the "Negative Answers" section:
skipping to change at page 15, line 13 skipping to change at page 15, line 13
* in "Appendix A": * in "Appendix A":
+ added the phrase " offered by data providers on the web" + added the phrase " offered by data providers on the web"
after the phrase "Looking at the implementation experiences after the phrase "Looking at the implementation experiences
of partial response"; of partial response";
+ replaced the phrase "servers should define a strategy" with + replaced the phrase "servers should define a strategy" with
the phrase "servers have to define a strategy"; the phrase "servers have to define a strategy";
+ replaced the term "latter approach" with the term "field set + replaced the term "latter approach" with the term "field set
approach" in the "Appendix A.1" section; approach" in the "Appendix A.1" section;
* updated the "Acknowledgements" section. * updated the "Acknowledgements" section.
15: Minor edit in the "Appendix A.1" section. 15: Minor edit in the "Appendix A.1" section;
16: Changed a figure containing only an RDAP query into text. Made
the RDAP queries uniform. Other minor edits.
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. 27 change blocks. 
33 lines changed or deleted 34 lines changed or added

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