1 Internet Engineering Task Force (IETF)                       M. Loffredo   
    2 Request for Comments: 8982                                 M. Martinelli   
    3 Category: Standards Track                            IIT-CNR/Registro.it   
    4 ISSN: 2070-1721                                            February 2021   
    5                                                                            
    6                                                                            
    7        Registration Data Access Protocol (RDAP) Partial Response           
    8                                                                            
    9 Abstract                                                                   
   10                                                                            
   11    The Registration Data Access Protocol (RDAP) does not include           
   12    capabilities to request partial responses.  Servers will only return    
   13    full responses that include all of the information that a client is     
   14    authorized to receive.  A partial response capability that limits the   
   15    amount of information returned, especially in the case of search        
   16    queries, could bring benefits to both clients and servers.  This        
   17    document describes an RDAP query extension that allows clients to       
   18    specify their preference for obtaining a partial response.              
   19                                                                            
   20 Status of This Memo                                                        
   21                                                                            
   22    This is an Internet Standards Track document.                           
   23                                                                            
   24    This document is a product of the Internet Engineering Task Force       
   25    (IETF).  It represents the consensus of the IETF community.  It has     
   26    received public review and has been approved for publication by the     
   27    Internet Engineering Steering Group (IESG).  Further information on     
   28    Internet Standards is available in Section 2 of RFC 7841.               
   29                                                                            
   30    Information about the current status of this document, any errata,      
   31    and how to provide feedback on it may be obtained at                    
   32    https://www.rfc-editor.org/info/rfc8982.                                
   33                                                                            
   34 Copyright Notice                                                           
   35                                                                            
   36    Copyright (c) 2021 IETF Trust and the persons identified as the         
   37    document authors.  All rights reserved.                                 
   38                                                                            
   39    This document is subject to BCP 78 and the IETF Trust's Legal           
   40    Provisions Relating to IETF Documents                                   
   41    (https://trustee.ietf.org/license-info) in effect on the date of        
   42    publication of this document.  Please review these documents            
   43    carefully, as they describe your rights and restrictions with respect   
   44    to this document.  Code Components extracted from this document must    
   45    include Simplified BSD License text as described in Section 4.e of      
   46    the Trust Legal Provisions and are provided without warranty as         
   47    described in the Simplified BSD License.                                
   48                                                                            
   49 Table of Contents                                                          
   50                                                                            
   51    1.  Introduction                                                        
   52      1.1.  Conventions Used in This Document                               
   53    2.  RDAP Path Segment Specification                                     
   54      2.1.  Subsetting Metadata                                             
   55        2.1.1.  RDAP Conformance                                            
   56        2.1.2.  Representing Subsetting Links                               
   57    3.  Dealing with Relationships                                          
   58    4.  Basic Field Sets                                                    
   59    5.  Negative Answers                                                    
   60    6.  IANA Considerations                                                 
   61    7.  Security Considerations                                             
   62    8.  References                                                          
   63      8.1.  Normative References                                            
   64      8.2.  Informative References                                          
   65    Appendix A.  Approaches to Partial Response Implementation              
   66      A.1.  Specific Issues Raised by RDAP                                  
   67    Acknowledgements                                                        
   68    Authors' Addresses                                                      
   69                                                                            
   70 1.  Introduction                                                           
   71                                                                            
   72    The use of partial responses in RESTful API [REST] design is very       
   73    common.  The rationale is quite simple: instead of returning objects    
   74    in API responses with all data fields, only a subset of the fields in   
   75    each result object is returned.  The benefit is obvious: less data      
   76    transferred over the network means less bandwidth usage, faster         
   77    server responses, less CPU time spent both on the server and the        
   78    client, and less memory usage on the client.                            
   79                                                                            
   80    Currently, RDAP does not provide a client with any way to request a     
   81    partial response.  Servers can only provide the client with a full      
   82    response [RFC7483].  Servers cannot limit the amount of information     
   83    returned in a response based on a client's preferences, and this        
   84    creates inefficiencies.                                                 
   85                                                                            
   86    The protocol described in this specification extends RDAP search        
   87    capabilities to enable partial responses through the provisioning of    
   88    predefined sets of fields that clients can submit to an RDAP service    
   89    by adding a new query parameter.  The service is implemented using      
   90    the Hypertext Transfer Protocol (HTTP) [RFC7230] and the conventions    
   91    described in [RFC7480].                                                 
   92                                                                            
   93 1.1.  Conventions Used in This Document                                    
   94                                                                            
   95    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",     
   96    "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and    
   97    "OPTIONAL" in this document are to be interpreted as described in       
   98    BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all      
   99    capitals, as shown here.                                                
  100                                                                            
  101 2.  RDAP Path Segment Specification                                        
  102                                                                            
  103    The path segment defined in this section is an OPTIONAL extension of    
  104    search path segments defined in [RFC7482].  This document defines an    
  105    RDAP query parameter, "fieldSet", whose value is a non-empty string     
  106    identifying a server-defined set of fields returned in place of the     
  107    full response.  The field sets supported by a server are usually        
  108    described in out-of-band documents (e.g., RDAP profile) together with   
  109    other features.  Moreover, this document defines in Section 2.1 an      
  110    in-band mechanism by means of which servers can provide clients with    
  111    basic information about the supported field sets.                       
  112                                                                            
  113    The following is an example of an RDAP query including the "fieldSet"   
  114    parameter:                                                              
  115                                                                            
  116    https://example.com/rdap/domains?name=example*.com&fieldSet=afieldset   
  117                                                                            
  118    This solution can be implemented by RDAP providers with less effort     
  119    than field selection and is easily requested by clients.  The           
  120    considerations that have led to this solution are described in more     
  121    detail in Appendix A.                                                   
  122                                                                            
  123 2.1.  Subsetting Metadata                                                  
  124                                                                            
  125    According to most advanced principles in REST design, collectively      
  126    known as "Hypermedia as the Engine of Application State" (HATEOAS)      
  127    [HATEOAS], a client entering a REST application through an initial      
  128    URI should use server-provided links to dynamically discover            
  129    available actions and access the resources it needs.  In this way,      
  130    the client is not required to have prior knowledge of the service       
  131    nor, consequently, to hard-code the URIs of different resources.        
  132    This allows the server to make URI changes as the API evolves without   
  133    breaking clients.  Definitively, a REST service should be as self-      
  134    descriptive as possible.                                                
  135                                                                            
  136    Therefore, servers implementing the query parameter described in this   
  137    specification SHOULD provide additional information in their            
  138    responses about the available field sets.  Such information is          
  139    collected in a new JSON data structure named "subsetting_metadata"      
  140    containing the following properties:                                    
  141                                                                            
  142    "currentFieldSet": "String" (REQUIRED)                                  
  143       either the value of the "fieldSet" parameter as specified in the     
  144       query string, or the field set applied by default.                   
  145                                                                            
  146    "availableFieldSets": "AvailableFieldSet[]" (OPTIONAL)                  
  147       an array of objects, with each element describing an available       
  148       field set.  The AvailableFieldSet object includes the following      
  149       members:                                                             
  150                                                                            
  151       "name": "String" (REQUIRED)                                          
  152          the field set name.                                               
  153                                                                            
  154       "default": "Boolean" (REQUIRED)                                      
  155          indicator of whether the field set is applied by default.  An     
  156          RDAP server MUST define only one default field set.               
  157                                                                            
  158       "description": "String" (OPTIONAL)                                   
  159          a human-readable description of the field set.                    
  160                                                                            
  161       "links": "Link[]" (OPTIONAL)                                         
  162          an array of links as described in [RFC8288] containing the        
  163          query string that applies the field set (see Section 2.1.2).      
  164                                                                            
  165 2.1.1.  RDAP Conformance                                                   
  166                                                                            
  167    Servers returning the "subsetting_metadata" section in their            
  168    responses MUST include "subsetting" in the rdapConformance array.       
  169                                                                            
  170 2.1.2.  Representing Subsetting Links                                      
  171                                                                            
  172    An RDAP server MAY use the "links" array of the "subsetting_metadata"   
  173    element to provide ready-made references [RFC8288] to the available     
  174    field sets (Figure 1).  The target URI in each link is the reference    
  175    to an alternative to the current view of results identified by the      
  176    context URI.                                                            
  177                                                                            
  178    The "value", "rel", and "href" JSON values MUST be specified.  All      
  179    other JSON values are OPTIONAL.                                         
  180                                                                            
  181    {                                                                       
  182      "rdapConformance": [                                                  
  183        "rdap_level_0",                                                     
  184        "subsetting"                                                        
  185      ],                                                                    
  186      ...                                                                   
  187      "subsetting_metadata": {                                              
  188        "currentFieldSet": "afieldset",                                     
  189        "availableFieldSets": [                                             
  190          {                                                                 
  191          "name": "anotherfieldset",                                        
  192          "description": "Contains some fields",                            
  193          "default": false,                                                 
  194          "links": [                                                        
  195            {                                                               
  196            "value": "https://example.com/rdap/domains?name=example*.com    
  197                      &fieldSet=afieldset",                                 
  198            "rel": "alternate",                                             
  199            "href": "https://example.com/rdap/domains?name=example*.com     
  200                     &fieldSet=anotherfieldset",                            
  201            "title": "Result Subset Link",                                  
  202            "type": "application/rdap+json"                                 
  203            }                                                               
  204          ]                                                                 
  205          },                                                                
  206        ...                                                                 
  207        ]                                                                   
  208      },                                                                    
  209      ...                                                                   
  210      "domainSearchResults": [                                              
  211        ...                                                                 
  212      ]                                                                     
  213    }                                                                       
  214                                                                            
  215            Figure 1: Example of a "subsetting_metadata" Instance           
  216                                                                            
  217 3.  Dealing with Relationships                                             
  218                                                                            
  219    Representation of second-level objects within a field set produces      
  220    additional considerations.  Since the representation of the topmost     
  221    returned objects will vary according to the field set in use, the       
  222    response may contain no relationships (e.g., for an abbreviated field   
  223    set) or may contain associated objects as in a normal RDAP query        
  224    response.  Each field set can indicate the format of the additional     
  225    objects to be returned, in the same manner that the format of the       
  226    topmost objects is controlled by the field set.                         
  227                                                                            
  228 4.  Basic Field Sets                                                       
  229                                                                            
  230    This section defines three basic field sets that servers MAY            
  231    implement to facilitate their interaction with clients:                 
  232                                                                            
  233    "id":  The server provides only the key field; "handle" for entities,   
  234       and "ldhName" for domains and nameservers.  If a returned domain     
  235       or nameserver is an Internationalized Domain Name (IDN) [RFC5890],   
  236       then the "unicodeName" field MUST additionally be included in the    
  237       response.  This field set could be used when the client wants to     
  238       obtain a collection of object identifiers (Figure 2).                
  239                                                                            
  240    "brief":  The field set contains the fields that can be included in a   
  241       "short" response.  This field set could be used when the client is   
  242       asking for a subset of the full response that provides only basic    
  243       knowledge of each object.                                            
  244                                                                            
  245    "full":  The field set contains all of the information the server can   
  246       provide for a particular object.                                     
  247                                                                            
  248    The "objectClassName" field is implicitly included in each of the       
  249    above field sets.  RDAP providers SHOULD include a "links" field        
  250    indicating the "self" link relationship.  RDAP providers MAY also add   
  251    any property providing service information.                             
  252                                                                            
  253    Fields included in the "brief" and "full" field set responses MUST      
  254    take into account the user's access and authorization levels.           
  255                                                                            
  256    {                                                                       
  257      "rdapConformance": [                                                  
  258        "rdap_level_0",                                                     
  259        "subsetting"                                                        
  260      ],                                                                    
  261      ...                                                                   
  262      "domainSearchResults": [                                              
  263        {                                                                   
  264          "objectClassName": "domain",                                      
  265          "ldhName": "example1.com",                                        
  266          "links": [                                                        
  267            {                                                               
  268            "value": "https://example.com/rdap/domain/example1.com",        
  269            "rel": "self",                                                  
  270            "href": "https://example.com/rdap/domain/example1.com",         
  271            "type": "application/rdap+json"                                 
  272            }                                                               
  273          ]                                                                 
  274        },                                                                  
  275        {                                                                   
  276          "objectClassName": "domain",                                      
  277          "ldhName": "example2.com",                                        
  278          "links": [                                                        
  279            {                                                               
  280            "value": "https://example.com/rdap/domain/example2.com",        
  281            "rel": "self",                                                  
  282            "href": "https://example.com/rdap/domain/example2.com",         
  283            "type": "application/rdap+json"                                 
  284            }                                                               
  285          ]                                                                 
  286        },                                                                  
  287        ...                                                                 
  288      ]                                                                     
  289    }                                                                       
  290                                                                            
  291      Figure 2: Example of RDAP Response According to the "id" Field Set    
  292                                                                            
  293 5.  Negative Answers                                                       
  294                                                                            
  295    Each request including an empty or unsupported "fieldSet" value MUST    
  296    produce an HTTP 400 (Bad Request) response code.  Optionally, the       
  297    response MAY include additional information regarding the supported     
  298    field sets in the HTTP entity body (Figure 3).                          
  299                                                                            
  300    {                                                                       
  301        "errorCode": 400,                                                   
  302        "title": "Field set 'unknownfieldset' is not valid",                
  303        "description": [                                                    
  304            "Supported field sets are: 'afieldset', 'anotherfieldset'."     
  305        ]                                                                   
  306                                                                            
  307    }                                                                       
  308                                                                            
  309       Figure 3: Example of RDAP Error Response Due to an Invalid Field     
  310                         Set Included in the Request                        
  311                                                                            
  312 6.  IANA Considerations                                                    
  313                                                                            
  314    IANA has registered the following value in the "RDAP Extensions"        
  315    registry:                                                               
  316                                                                            
  317    Extension identifier:  subsetting                                       
  318    Registry operator:  Any                                                 
  319    Published specification:  RFC 8982                                      
  320    Contact:  IETF <iesg@ietf.org>                                          
  321    Intended usage:  This extension describes a best practice for partial   
  322       response provisioning.                                               
  323                                                                            
  324 7.  Security Considerations                                                
  325                                                                            
  326    A search query typically requires more server resources (such as        
  327    memory, CPU cycles, and network bandwidth) when compared to a lookup    
  328    query.  This increases the risk of server resource exhaustion and       
  329    subsequent denial of service.  This risk can be mitigated by            
  330    supporting the return of partial responses combined with other          
  331    strategies (e.g., restricting search functionality, limiting the rate   
  332    of search requests, and truncating and paging results).                 
  333                                                                            
  334    Support for partial responses gives RDAP operators the ability to       
  335    implement data access control policies based on the HTTP                
  336    authentication mechanisms described in [RFC7481].  RDAP operators can   
  337    vary the information returned in RDAP responses based on a client's     
  338    access and authorization levels.  For example:                          
  339                                                                            
  340    *  the list of fields for each set can differ based on the client's     
  341       access and authorization levels;                                     
  342                                                                            
  343    *  the set of available field sets could be restricted based on the     
  344       client's access and authorization levels.                            
  345                                                                            
  346    Servers can also define different result limits according to the        
  347    available field sets, so a more flexible truncation strategy can be     
  348    implemented.  The new query parameter presented in this document        
  349    provides RDAP operators with a way to implement a server that reduces   
  350    inefficiency risks.                                                     
  351                                                                            
  352 8.  References                                                             
  353                                                                            
  354 8.1.  Normative References                                                 
  355                                                                            
  356    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate          
  357               Requirement Levels", BCP 14, RFC 2119,                       
  358               DOI 10.17487/RFC2119, March 1997,                            
  359               <https://www.rfc-editor.org/info/rfc2119>.                   
  360                                                                            
  361    [RFC5890]  Klensin, J., "Internationalized Domain Names for             
  362               Applications (IDNA): Definitions and Document Framework",    
  363               RFC 5890, DOI 10.17487/RFC5890, August 2010,                 
  364               <https://www.rfc-editor.org/info/rfc5890>.                   
  365                                                                            
  366    [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer   
  367               Protocol (HTTP/1.1): Message Syntax and Routing",            
  368               RFC 7230, DOI 10.17487/RFC7230, June 2014,                   
  369               <https://www.rfc-editor.org/info/rfc7230>.                   
  370                                                                            
  371    [RFC7480]  Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the    
  372               Registration Data Access Protocol (RDAP)", RFC 7480,         
  373               DOI 10.17487/RFC7480, March 2015,                            
  374               <https://www.rfc-editor.org/info/rfc7480>.                   
  375                                                                            
  376    [RFC7481]  Hollenbeck, S. and N. Kong, "Security Services for the       
  377               Registration Data Access Protocol (RDAP)", RFC 7481,         
  378               DOI 10.17487/RFC7481, March 2015,                            
  379               <https://www.rfc-editor.org/info/rfc7481>.                   
  380                                                                            
  381    [RFC7482]  Newton, A. and S. Hollenbeck, "Registration Data Access      
  382               Protocol (RDAP) Query Format", RFC 7482,                     
  383               DOI 10.17487/RFC7482, March 2015,                            
  384               <https://www.rfc-editor.org/info/rfc7482>.                   
  385                                                                            
  386    [RFC7483]  Newton, A. and S. Hollenbeck, "JSON Responses for the        
  387               Registration Data Access Protocol (RDAP)", RFC 7483,         
  388               DOI 10.17487/RFC7483, March 2015,                            
  389               <https://www.rfc-editor.org/info/rfc7483>.                   
  390                                                                            
  391    [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC       
  392               2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,     
  393               May 2017, <https://www.rfc-editor.org/info/rfc8174>.         
  394                                                                            
  395    [RFC8288]  Nottingham, M., "Web Linking", RFC 8288,                     
  396               DOI 10.17487/RFC8288, October 2017,                          
  397               <https://www.rfc-editor.org/info/rfc8288>.                   
  398                                                                            
  399 8.2.  Informative References                                               
  400                                                                            
  401    [CQL]      Whitaker, G., "Catnap Query Language Reference", commit      
  402               d4f402c, September 2017,                                     
  403               <https://github.com/gregwhitaker/catnap/wiki/Catnap-Query-   
  404               Language-Reference>.                                         
  405                                                                            
  406    [HATEOAS]  Jedrzejewski, B., "HATEOAS - a simple explanation",          
  407               February 2018, <https://www.e4developer.com/2018/02/16/      
  408               hateoas-simple-explanation/>.                                
  409                                                                            
  410    [REST]     Fielding, R., "Architectural Styles and the Design of        
  411               Network-based Software Architectures", Ph.D. Dissertation,   
  412               University of California, Irvine, 2000,                      
  413               <https://www.ics.uci.edu/~fielding/pubs/dissertation/        
  414               fielding_dissertation.pdf>.                                  
  415                                                                            
  416 Appendix A.  Approaches to Partial Response Implementation                 
  417                                                                            
  418    Looking at the implementation experiences of partial responses          
  419    offered by data providers on the web, two approaches are observed:      
  420                                                                            
  421    *  the client explicitly describes the data fields to be returned;      
  422                                                                            
  423    *  the client describes a name identifying a server-defined set of      
  424       data fields.                                                         
  425                                                                            
  426    The former is more flexible than the latter because clients can         
  427    specify all the data fields they need.  However, it has some            
  428    drawbacks:                                                              
  429                                                                            
  430    *  Fields have to be declared according to a given syntax.  This is a   
  431       simple task when the data structure of the object is flat, but it    
  432       is much more difficult when the object has a tree structure like     
  433       that of a JSON object.  The presence of arrays and deep nested       
  434       objects complicate both the syntax definition of the query and,      
  435       consequently, the processing required on the server side.            
  436                                                                            
  437    *  Clients need to recognize the returned data structure to avoid       
  438       cases when the requested fields are invalid.                         
  439                                                                            
  440    *  The request of some fields might not match the client's access and   
  441       authorization levels.  Clients might request unauthorized fields,    
  442       and servers have to define a strategy for responding such as         
  443       always returning an error response or returning a response that      
  444       ignores the unauthorized fields.                                     
  445                                                                            
  446 A.1.  Specific Issues Raised by RDAP                                       
  447                                                                            
  448    In addition to those listed above, RDAP responses raise some specific   
  449    issues:                                                                 
  450                                                                            
  451    *  Relevant entity object information is included in a jCard, but       
  452       such information cannot be easily selected because it is split       
  453       into the items of a jagged array.                                    
  454                                                                            
  455    *  RDAP responses contain some properties providing service             
  456       information (e.g., rdapConformance, links, notices, remarks,         
  457       etc.), which are not normally selected but are just as important.    
  458       They could be returned anyway but, in this case, the server would    
  459       provide unrequested data.                                            
  460                                                                            
  461    It is possible to address these issues.  For example, the Catnap        
  462    Query Language [CQL] is a comprehensive expression language that can    
  463    be used to customize the JSON response of a RESTful web service.        
  464    Application of CQL to RDAP responses would explicitly identify the      
  465    output fields that would be acceptable when a few fields are            
  466    requested but it would become very complicated when processing a        
  467    larger number of fields.  In the following, two CQL expressions for a   
  468    domain search query are shown (Figure 4).  In the first, only           
  469    objectClassName and ldhName are requested.  In the second, the fields   
  470    of a possible WHOIS-like response are listed.                           
  471                                                                            
  472    https://example.com/rdap/domains?name=example*.com                      
  473            &fields=domainSearchResults(objectClassName,ldhName)            
  474                                                                            
  475    https://example.com/rdap/domains?name=example*.com                      
  476            &fields=domainSearchResults(objectClassName,ldhName,            
  477                    unicodeName,                                            
  478                    status,                                                 
  479                    events(eventAction,eventDate),                          
  480                    entities(objectClassName,handle,roles),                 
  481                    nameservers(objectClassName,ldhName))                   
  482                                                                            
  483       Figure 4: Examples of CQL Expressions for a Domain Search Query      
  484                                                                            
  485    The field set approach seems to facilitate RDAP interoperability.       
  486    Servers can define basic field sets that, if known to clients, can      
  487    increase the probability of obtaining a valid response.  The usage of   
  488    field sets makes the query string less complex.  Moreover, the          
  489    definition of predefined sets of fields makes it easier to establish    
  490    result limits.                                                          
  491                                                                            
  492    Finally, considering that there is no real need for RDAP users to       
  493    have the maximum flexibility in defining all the possible sets of       
  494    logically connected fields (e.g., users interested in domains usually   
  495    need to know the status, the creation date, and the expiry date of      
  496    each domain), the field set approach is preferred.                      
  497                                                                            
  498 Acknowledgements                                                           
  499                                                                            
  500    The authors would like to acknowledge Scott Hollenbeck, Tom Harrison,   
  501    Karl Heinz Wolf, Jasdip Singh, Patrick Mevzek, Benjamin Kaduk, Roman    
  502    Danyliw, Murray Kucherawy, Erik Kline, and Robert Wilton for their      
  503    contribution to this document.                                          
  504                                                                            
  505 Authors' Addresses                                                         
  506                                                                            
  507    Mario Loffredo                                                          
  508    IIT-CNR/Registro.it                                                     
  509    Via Moruzzi,1                                                           
  510    56124 Pisa                                                              
  511    Italy                                                                   
  512                                                                            
  513    Email: mario.loffredo@iit.cnr.it                                        
  514    URI:   https://www.iit.cnr.it                                           
  515                                                                            
  516                                                                            
  517    Maurizio Martinelli                                                     
  518    IIT-CNR/Registro.it                                                     
  519    Via Moruzzi,1                                                           
  520    56124 Pisa                                                              
  521    Italy                                                                   
  522                                                                            
  523    Email: maurizio.martinelli@iit.cnr.it                                   
  524    URI:   https://www.iit.cnr.it                                           
  525                                                                            

The IETF is responsible for the creation and maintenance of the DNS RFCs. The ICANN DNS RFC annotation project provides a forum for collecting community annotations on these RFCs as an aid to understanding for implementers and any interested parties. The annotations displayed here are not the result of the IETF consensus process.

This RFC is included in the DNS RFCs annotation project whose home page is here.