draft-ietf-regext-rdap-partial-response-11.txt   draft-ietf-regext-rdap-partial-response-12.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: November 30, 2020 May 29, 2020 Expires: December 19, 2020 June 17, 2020
Registration Data Access Protocol (RDAP) Partial Response Registration Data Access Protocol (RDAP) Partial Response
draft-ietf-regext-rdap-partial-response-11 draft-ietf-regext-rdap-partial-response-12
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 includes 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
specify their preference for obtaining a partial response. specify their preference for obtaining a partial response.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 November 30, 2020. This Internet-Draft will expire on December 19, 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 19 skipping to change at page 2, line 19
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions Used in This Document . . . . . . . . . . . . 3 1.1. Conventions Used in This Document . . . . . . . . . . . . 3
2. RDAP Path Segment Specification . . . . . . . . . . . . . . . 3 2. RDAP Path Segment Specification . . . . . . . . . . . . . . . 3
2.1. Subsetting Metadata . . . . . . . . . . . . . . . . . . . 3 2.1. Subsetting Metadata . . . . . . . . . . . . . . . . . . . 3
2.1.1. RDAP Conformance . . . . . . . . . . . . . . . . . . 4 2.1.1. RDAP Conformance . . . . . . . . . . . . . . . . . . 4
2.1.2. Representing Subsetting Links . . . . . . . . . . . . 4 2.1.2. Representing Subsetting Links . . . . . . . . . . . . 4
3. Dealing with Relationships . . . . . . . . . . . . . . . . . 5 3. Dealing with Relationships . . . . . . . . . . . . . . . . . 5
4. Basic Field Sets . . . . . . . . . . . . . . . . . . . . . . 6 4. Basic Field Sets . . . . . . . . . . . . . . . . . . . . . . 6
5. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 7 5. Negative Answers . . . . . . . . . . . . . . . . . . . . . . 7
6. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 8 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8
6.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 8
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 7.2. APNIC . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 9.1. Normative References . . . . . . . . . . . . . . . . . . 9
10.1. Normative References . . . . . . . . . . . . . . . . . . 10 9.2. Informative References . . . . . . . . . . . . . . . . . 10
10.2. Informative References . . . . . . . . . . . . . . . . . 11
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 . . . . . . . . . . . . . 12
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 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: less 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 (e.g. LinkedIn [LINKEDIN], Facebook Several leading API providers [LINKEDIN] [FACEBOOK] [GOOGLE]
[FACEBOOK], Google [GOOGLE]) implement partial response features by implement partial response features by providing an optional query
providing an optional query parameter by which clients identify the parameter through which clients identify the fields they wish to
fields they wish to receive. Support for partial responses is also receive. Support for partial responses is also considered a leading
considered a leading principle by many best practice guidelines in principle by many best practice guidelines in REST API implementation
REST API implementation ([REST-API1], [REST-API2]) in order to [REST-API1] [REST-API2] in order to improve performance, save on
improve performance, save on bandwidth and possibly accelerate the bandwidth and possibly accelerate the overall interaction. In other
overall interaction. In other contexts, for example in digital contexts, for example in digital libraries and bibliographic
libraries and bibliographic catalogues, servers can provide responses catalogues, servers can respond according to different element sets
according to different element sets (i.e. "brief" to get back a short (i.e. "brief" to obtain a short response and "full" to obtain the
response and "full" to get back the complete response). 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 the Hypertext Transfer Protocol (HTTP) [RFC7230] and the conventions
conventions described in RFC 7480 ([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", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14 [RFC2119] document are to be interpreted as described in BCP 14 [RFC2119]
[RFC8174] when, and only when, they appear in all capitals, as shown [RFC8174] when, and only when, they appear in all capitals, as shown
here. 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 RFC 7482 ([RFC7482]). This document search path segments defined in [RFC7482]. This document defines an
defines an RDAP query parameter, "fieldSet", whose value is a string RDAP query parameter, "fieldSet", whose value is a string identifying
identifying a server-defined set of supported fields (Figure 1). a server-defined set of supported fields (Figure 1).
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.
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)
([HATEOAS]), a client entering a REST application through an initial [HATEOAS], a client entering a REST application through an initial
URI should use server-provided links to dynamically discover URI should use server-provided links to dynamically discover
available actions and access the resources it needs. In this way, available actions and access the resources it needs. In this way,
the client is not required to have prior knowledge of the service the client is not required to have prior knowledge of the service
and, consequently, to hard code the URIs of different resources. and, consequently, to hard code the URIs of different resources.
This allows the server to make URI changes as the API evolves without This allows the server to make URI changes as the API evolves without
breaking clients. Definitively, a REST service should be as self- breaking clients. Definitively, a REST service should be as self-
descriptive as possible. descriptive as possible.
Therefore, servers implementing the query parameter described in this Therefore, servers implementing the query parameter described in this
specification SHOULD provide additional information in their specification SHOULD provide additional information in their
skipping to change at page 4, line 31 skipping to change at page 4, line 31
o "availableFieldSets": "AvailableFieldSet[]" (OPTIONAL) an array of o "availableFieldSets": "AvailableFieldSet[]" (OPTIONAL) an array of
objects, with each element describing an available field set. objects, with each element describing an available field set.
Members are: Members are:
* "name": "String" (REQUIRED) the field set name; * "name": "String" (REQUIRED) the field set name;
* "default": "Boolean" (REQUIRED) whether the field set is * "default": "Boolean" (REQUIRED) whether the field set is
applied by default; applied by default;
* "description": "String" (OPTIONAL) a human-readable description * "description": "String" (OPTIONAL) a human-readable description
of the field set; of the field set;
* "links": "Link[]" (OPTIONAL) an array of links as described in * "links": "Link[]" (OPTIONAL) an array of links as described in
RFC 8288 ([RFC8288]) containing the query string that applies [RFC8288] containing the query string that applies the field
the field set. set.
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 2). The target URI in each link is the reference
to an alternate view of the results with respect to the current view to an alternative to the current view of results identified by the
of the results identified by the context URI. context URI.
{ {
"rdapConformance": [ "rdapConformance": [
"rdap_level_0", "rdap_level_0",
"subsetting" "subsetting"
], ],
... ...
"subsetting_metadata": { "subsetting_metadata": {
"currentFieldSet": "afieldset", "currentFieldSet": "afieldset",
"availableFieldSets": [ "availableFieldSets": [
skipping to change at page 6, line 13 skipping to change at page 6, line 13
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, respectively:
"handle" for entities, "ldhName" for domains and nameservers. If "handle" for entities, "ldhName" for domains and nameservers. If
a returned domain or nameserver is an Internationalized Domain a returned domain or nameserver is an Internationalized Domain
Name (IDN, [RFC5890]), then the "unicodeName" field MUST be Name (IDN) [RFC5890], then the "unicodeName" field MUST 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 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
skipping to change at page 8, line 5 skipping to change at page 8, line 5
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 unsupported field set SHOULD produce an
HTTP 400 (Bad Request) response code. Optionally, the response MAY HTTP 400 (Bad Request) response code. Optionally, the response MAY
include additional information regarding the negative answer in the include additional information regarding the negative answer in the
HTTP entity body. HTTP entity body.
6. Implementation Status 6. IANA Considerations
IANA is requested to register the following value in the RDAP
Extensions Registry:
Extension identifier: subsetting
Registry operator: Any
Published specification: This document.
Contact: IESG <iesg@ietf.org>
Intended usage: This extension describes best practice for partial
response provisioning.
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
Internet-Draft, and is based on a proposal described in RFC 7942 Internet-Draft, and is based on a proposal described in [RFC7942].
([RFC7942]). The description of implementations in this section is The description of implementations in this section is intended to
intended to assist the IETF in its decision processes in progressing assist the IETF in its decision processes in progressing drafts to
drafts to RFCs. Please note that the listing of any individual RFCs. Please note that the listing of any individual implementation
implementation here does not imply endorsement by the IETF. here does not imply endorsement by the IETF. Furthermore, no effort
Furthermore, no effort has been spent to verify the information has been spent to verify the information presented here that was
presented here that was supplied by IETF contributors. This is not supplied by IETF contributors. This is not intended as, and must not
intended as, and must not be construed to be, a catalog of available be construed to be, a catalog of available implementations or their
implementations or their features. Readers are advised to note that features. Readers are advised to note that other implementations may
other implementations may exist. exist.
According to RFC 7942, "this will allow reviewers and working groups According to RFC 7942, "this will allow reviewers and working groups
to assign due consideration to documents that have the benefit of to assign due consideration to documents that have the benefit of
running code, which may serve as evidence of valuable experimentation running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature. and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as It is up to the individual working groups to use this information as
they see fit". they see fit".
6.1. IIT-CNR/Registro.it 7.1. IIT-CNR/Registro.it
Responsible Organization: Institute of Informatics and Telematics Responsible Organization: Institute of Informatics and Telematics
of National Research Council (IIT-CNR)/Registro.it of the National Research Council (IIT-CNR)/Registro.it
Location: https://rdap.pubtest.nic.it/ Location: https://rdap.pubtest.nic.it/
Description: This implementation includes support for RDAP queries Description: This implementation includes support for RDAP queries
using data from .it public test environment. using data from .it public test environment.
Level of Maturity: This is an "alpha" test implementation. Level of Maturity: This is an "alpha" test implementation.
Coverage: This implementation includes all of the features Coverage: This implementation includes all of the features
described in this specification. described in this specification.
Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it
6.2. APNIC 7.2. APNIC
Responsible Organization: Asia-Pacific Network Information Centre Responsible Organization: Asia-Pacific Network Information Centre
Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/partial- Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/partial-
response response
Description: A proof-of-concept for RDAP mirroring. Description: A proof-of-concept for RDAP mirroring.
Level of Maturity: This is a proof-of-concept implementation. Level of Maturity: This is a proof-of-concept implementation.
Coverage: This implementation includes all of the features Coverage: This implementation includes all of the features
described in this specification. described in this specification.
Contact Information: Tom Harrison, tomh@apnic.net Contact Information: Tom Harrison, tomh@apnic.net
7. IANA Considerations
IANA is requested to register the following value in the RDAP
Extensions Registry:
Extension identifier: subsetting
Registry operator: Any
Published specification: This document.
Contact: IESG <iesg@ietf.org>
Intended usage: This extension describes a best practice for
partial response provisioning.
8. Security Considerations 8. Security Considerations
A search query typically requires more server resources (such as A search query typically requires more server resources (such as
memory, CPU cycles, and network bandwidth) when compared to a lookup memory, CPU cycles, and network bandwidth) when compared to a lookup
query. This increases the risk of server resource exhaustion and query. This increases the risk of server resource exhaustion and
subsequent denial of service due to abuse. Thiss risk can be subsequent denial of service due to abuse. This risk can be
mitigated by supporting return of partial responses combined with mitigated by supporting the return of partial responses combined with
other strategies (e.g. restricting search functionality, limiting the other strategies (e.g. restricting search functionality, limiting the
rate of search requests, and truncating and paging results). rate of search requests, and truncating and paging results).
Support for partial responses gives RDAP operators the ability to Support for partial responses gives RDAP operators the ability to
implement data access control policies based on the HTTP implement data access control policies based on the HTTP
authentication mechanisms described in RFC 7481 ([RFC7481]). RDAP authentication mechanisms described in [RFC7481]. RDAP operators can
operators can vary the information returned in RDAP responses based vary the information returned in RDAP responses based on a client's
on a client's access and authorization levels. For example: access and authorization levels. For example:
o The list of fields for each set can differ based on the client's o the list of fields for each set can differ based on the client's
access and authorization levels; access and authorization levels;
o The set of available field sets could be restricted based on the o the set of available field sets could be restricted based on the
client's access and authorization levels. client's access and authorization levels.
Servers can also define different result limits according to the Servers can also define different result limits according to the
available field sets, so a more flexible truncation strategy can be available field sets, so a more flexible truncation strategy can be
implemented. The new query parameter presented in this document implemented. The new query parameter presented in this document
provides RDAP operators with a way to implement a server that reduces provides RDAP operators with a way to implement a server that reduces
inefficiency risks. inefficiency risks.
9. Acknowledgements 9. References
The authors would like to acknowledge Scott Hollenbeck, Tom Harrison,
Karl Heinz Wolf, Jasdip Singh and Patrick Mevzek for their
contribution to this document.
10. References
10.1. Normative References 9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5890] Klensin, J., "Internationalized Domain Names for [RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework", Applications (IDNA): Definitions and Document Framework",
RFC 5890, DOI 10.17487/RFC5890, August 2010, RFC 5890, DOI 10.17487/RFC5890, August 2010,
<https://www.rfc-editor.org/info/rfc5890>. <https://www.rfc-editor.org/info/rfc5890>.
skipping to change at page 11, line 9 skipping to change at page 10, line 48
<https://www.rfc-editor.org/info/rfc7942>. <https://www.rfc-editor.org/info/rfc7942>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[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>.
10.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]
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 12, line 7 skipping to change at page 11, line 45
[REST-API2] [REST-API2]
Masse, M., "REST API Design Rulebook", October 2011. 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 described in Section 1, two
approaches to the implementation of partial response are observed: approaches to the implementation of partial response 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 describeds 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
the one 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 should define a strategy for providing a response, and servers should define a strategy for responding, such as
such as always returning an error response or returning a response always returning an error response or returning a response that
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's possible to address these issues. For example, the Catnap Query It is possible to address these issues. For example, the Catnap
Language ([CQL]) is a comprehensive expression language that can be Query Language [CQL] is a comprehensive expression language that can
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 some 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 4). 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 4: Examples of CQL expressions for a domain search query Figure 4: Examples of CQL expressions for a domain search query
The latter approach seems to facilitate RDAP interoperability. The latter 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 to get a valid response. The usage of field increase the probability of obtaining a valid response. The usage of
sets lets the query string be less complex. In addition, 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
logically connected fields (e.g. users interested in domains usually logically connected fields (e.g. users interested in domains usually
need to know the status, the creation date, and the expiry date of need to know the status, the creation date, and the expiry date of
each domain), the latter approach is preferred. each domain), the latter approach is preferred.
Appendix B. Change Log Acknowledgements
The authors would like to acknowledge Scott Hollenbeck, Tom Harrison,
Karl Heinz Wolf, Jasdip Singh and Patrick Mevzek for their
contribution to this document.
Change Log
00: Initial working group version ported from draft-loffredo-regext- 00: Initial working group version ported from draft-loffredo-regext-
rdap-partial-response-03 rdap-partial-response-03
01: Removed "FOR DISCUSSION" items. Changed the basic field sets 01: Removed "FOR DISCUSSION" items. Changed the basic field sets
from REQUIRED to OPTIONAL. Removed the definition of fields from REQUIRED to OPTIONAL. Removed the definition of fields
included in "brief" field set. Provided a more detailed included in "brief" field set. Provided a more detailed
description of "subsetting_metadata" structure. Removed some description of "subsetting_metadata" structure. Removed some
references. references.
02: Added the "Negative Answers" section. Changed "IANA 02: Added the "Negative Answers" section. Changed "IANA
Considerations" section. Considerations" section.
skipping to change at page 14, line 19 skipping to change at page 14, line 21
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 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.
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. 39 change blocks. 
93 lines changed or deleted 94 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/