Internet-Draft | rpp-architecture | March 2025 |
Kowalik | Expires 4 September 2025 | [Page] |
The Extensible Provisioning Protocol (EPP), standardized in 2009, has served the domain name industry well for domain name management. However, advancements in development, integration, and operational paradigms have led to a desire for a provisioning protocol leveraging the REST architectural style and JSON data-interchange format. This document defines the architecture for the RESTful Provisioning Protocol (RPP), aiming to standardize a REST-based protocol for provisioning services, initially focused on domain name, host, and contact management, while allowing for future extensibility. RPP is intended to co-exist with EPP, offering a modern alternative benefiting from the REST architectural style and widely adopted technologies. RPP aims for data model compatibility with EPP core objects.¶
When contributing to this document, please use the following GitHub project: https://github.com/pawel-kow/RPP-architecture.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 4 September 2025.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Extensible Provisioning Protocol (EPP) [RFC5730] has been a cornerstone protocol for domain name management. Recognizing the shift towards RESTful architectures and the widespread adoption of JSON, this document outlines the architecture of the RESTful Provisioning Protocol (RPP). RPP aims to provide a modern, standardized, and developer-friendly protocol for provisioning services, initially focusing on functional equivalents of EPP for domain names [RFC5731], hosts [RFC5732], and contacts [RFC5733]. RPP also considers DNS provisioning as a potential use case, aiming for a uniform API layer for various registry operations.¶
RPP is designed to leverage the benefits of REST, including statelessness, ease of integration, and compatibility with existing web infrastructure and tools such as OpenAPI, API gateways, and web application firewalls. By adopting JSON as the data-interchange format, RPP seeks to align with current development practices and the successful deployment patterns observed in protocols like RDAP [RFC9082]. The choice of REST and JSON also facilitates direct browser and mobile application integration.¶
This architecture document serves as a foundation for a series of specifications that will collectively define RPP. It details the layered approach, core components, and design considerations for building an interoperable and extensible provisioning protocol. RPP is intended to coexist with EPP, offering an alternative for implementers seeking a RESTful approach without aiming to replace EPP or define migration paths from EPP. RPP aims for data model compatibility with EPP core objects to allow automatic and mechanical mapping and conversion, especially for core objects (domain, contact, host).¶
This document uses terminology from RFC5730 [RFC5730] and broadly adopts the REST architectural principles as defined in [REST] and related RFCs.¶
Note: This list of requirements is based on the current (20.2.2025) state of discussion in RPP working group and may be changed in futher work [RPPReq].¶
RPP is designed to meet the following requirements:¶
This chapter provides an overview of the Resource Provisioning Protocol (RPP) architecture. A key design principle is the maximal reuse of existing web standards, particularly HTTP and REST principles. This allows RPP to leverage the well-established infrastructure and semantics of the web, focusing its own definitions on the specific domain of resource provisioning. Therefore, we assume:¶
The architecture is divided into three main layers: HTTP Transport, Data Representation, and Resource Definition. Each layer defines specific aspects of the protocol. This layered approach allows for clear separation of concerns, enabling independent evolution and extensibility of each layer.¶
+---------------------------------------------------------+ | HTTP Transport | | | | +-----------------------------------------------------+ | | | Data Representation | | | | | | | | +-------------------------------------------------+ | | | | | Encapsulation | | | | | | | | | | | | +---------------------------------------------+ | | | | | | | Data Structure | | | | | | | | | | | | | | | | +-----------------------------------------+ | | | | | | | | | Resource Description | | | | | | | | | | | | | | | | | | | | +--------------+ +--------------+ | <--------+ | | | | | | | | | | | | | | | | | | | | | Data | | Mapping | | | | | | | | | | | | | Elements --------> -------------+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +---^----------+ +--------------+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +--------------+ | | | | | | | | | | | | | | | | | | | | | | | | | Operations | | | | | | | | | | | +------- | | | | | | | | | | | | | | | | | | | | | | | +--------------+ | | | | | | | | | | | | | | | | | | | +-----------------------------------------+ | | | | | | | +---------------------------------------------+ | | | | | +-------------------------------------------------+ | | | +-----------------------------------------------------+ | +---------------------------------------------------------+¶
RPP adopts a Resource Oriented Architecture (ROA), aligning with RESTful principles. This approach treats all manageable entities as "resources," identified by unique URLs. Operations on these resources are performed through a uniform interface using HTTP methods (GET, POST, PUT, DELETE, PATCH). This contrasts with RPC-style protocols, which often define specific operations with custom parameters. ROA promotes a more standardized and interoperable approach, leveraging the existing web infrastructure and its well-defined semantics. Key aspects of ROA within RPP include:¶
This layer defines the transport mechanism for RPP messages, utilizing HTTP as the underlying protocol.¶
It encompasses aspects such as:¶
This layer focuses on the encapsulation and data representation of RPP messages. It defines the media type used to carry RPP data and supports various data representation formats.¶
It encompasses aspects such as:¶
This layer defines the structure and operations for each resource type, independent of media type or representation. It ensures resources are well-defined and allows for easy extensibility and compatibility with different media types.¶
It encompasses aspects such as:¶
This section provides further details on each layer of the RPP architecture.¶
RPP resources are addressed using URLs. Considerations include:¶
/domains/{domain-name}
, /contacts/{contact-id}
).¶
/domains/{domain-name}/contacts/
)¶
RPP URL structure will be designed to be human-readable, intuitive, and RESTful, allowing clients to easily navigate and interact with resources.¶
RPP would not require all URLs to be hard wired to server's RPP root URL. Instead, it would allow for relative URLs to be defined and discovered by the client. This would allow servers to distibute resources across multiple servers and URLs and allow for easier scaling.¶
As a matter of extensibility consideration RPP should allow for additional path segments to be added to the URLs and be discoverable by clients.¶
RPP will address the handling of Internationalized Domain Names (IDNs) in resource addressing. Specifications will define whether to use IDN or UTF-8 encoding directly in URLs and whether to employ redirects to canonical URLs or "see-also" linking for alternative representations. For example, a "see-also" link could point from a UTF-8 encoded URL to an IDN URL and vice versa, allowing clients to use either URL. Another way would be to always redirect to the canonical URL, which would be the IDN URL.¶
RPP operations are mapped to standard HTTP methods to leverage the uniform interface and RESTful principles:¶
EPP transfer commands (query and transform), being in fact a representation of a running process, may be modelled by a subresource /transfer
of the resource being transferred, with a PUT operation to initiate the transfer, GET operation to query the transfer status and POST operation to approve or reject the transfer. The same approach may apply when adding any other process to the resource, like domain restore.¶
EPP check command may be modelled either as a GET operation with a dedicated media type, a POST operation with Expect header or a HEAD verb - depending on the specific requirements of the check operation.¶
Other transform operations like renew, or restore which are not addressable resources in terms of REST may be either also modelled as POST requests with a dedicated media type, or be a convention of URLs with processing resources with only POST interface starting with underscore, e.g. /domains/{domain-name}/_renew
.¶
This basic set of rules and guidelines will be further refined in the RPP specifications and give an universal toolset for extending RPP with new resources and commands.¶
RPP utilizes both HTTP status codes and RPP-specific error codes within the response body for detailed error reporting.¶
RPP shall support identification of requests and reponses on both client side and server side with use of client provided identifiers and server provided identifiers. This will allow for tracking of requests and responses in case of errors, and for idempotency of requests. This should be defined outside of the Data Representation Layer (e.g. as HTTP Headers), to assure clear separation of resourse representation from performed actions. If possible existing mechanisms of HTTP shall be employed.¶
RPP shall benefit from HTTP standard caching mechanisms to enable standard components like proxies and caches to improve performance and reduce load on servers. RPP shall define caching policies for different resources and operations, including cache-control headers and ETag support.¶
RPP supports content negotiation to allow clients to specify preferred media types for request and response payloads using the HTTP 'Accept' and 'Content-Type' headers [RFC7231].¶
RPP may utilize the HTTP Prefer
header [RFC7240] with the "return" preference to allow clients to control the verbosity of responses. For example, clients not interested in full resource representations could use Prefer: return=minimal
to request minimal responses, reducing payload sizes and improving efficiency. The default behavior, without the Prefer
header, would be to return a full resource representation, similar to object info responses in EPP, especially after compound requests are completed.¶
RPP shall support language negotiation to enable clients to request responses in a preferred language using the HTTP 'Accept-Language' header [RFC7231].¶
RPP may define special resources for specific purposes:¶
RPP will define mechanisms for service discovery, allowing clients to dynamically discover RPP service endpoints and capabilities, reducing coupling between clients and servers.¶
/.well-known/rpp-capabilities
) for service discovery.¶
/.well-known/rpp-capabilities
there might be a separate discovery placed under /{resource-type}/.well-known/rpp-capabilities
e.g. /domains/.well-known/rpp-capabilities
.¶
This layer focuses on the encapsulation and data representation of RPP messages. It defines the media type used to carry RPP data and supports various data representation formats.¶
RPP will define the overall structure of the message payload carried by the chosen media type. Options for the data structure include:¶
The primary encapsulation for RPP data represetations shall be JSON, however RPP should be able to support extensions to support other formats like XML, JWT, JWT-SD or CBOR.¶
Change of encapsulation shall not affect the data structure, which should be defined independently of the encapsulation.¶
Together encapsulation and data structure would define the whole media type. So application/rpp+json would be the primary media type with "rpp" payloads in plain json format. application/epp+xml would be epp payload as per [RFC5730]. The Encapsulation and Data Structure can be also othewise combined as far as it is possible to represent the Data Structure in a given encapsulation. For example it would be straightforward to represent "rpp" structure in JWT format and application/rpp+jwt Media Type, but in order to represent epp structure in JWT format it would require first a mapping of epp messages on JSON instead of XML - rendering application/epp+jwt Media Type.¶
Each resource type, no matter if on a top level, being an independent provisioning object, or a subresource, being a part of another resource, shall be well defined including data elements and possible operations. A respource definition shall on the first level of abstraction be composable out of data elements, without any reference to the media type or representation. This will allow for easy extensibility and compatibility with different media types.¶
All resource types shall be defined in IANA registry in a way that allows fully automated processing of the resource definition, including data elements, operations and media type representation.¶
This part defines logical data elements for each resource type, which can also be re-used across resource types. It is abstracted from the actual transport and media type, focusing on the structure and constraints of data elements. Data element definition includes:¶
Data elements shall be defined in IANA registry in a way that allows for automated processing of the data element definition, including constraints and references to other data elements.¶
This layer defines the mapping of Data Elements onto the Data Representation Layer. For example in case of application/rpp+json media type, the mapping layer would define how the logical data units are represented in JSON format.¶
This additional level of indirection would allow usage of data formats defined outside of rpp specifications - for example usage of Verifiable Credentials or Verifiable Presentations as first class resource types for contacts in RPP, and mapping appropriate data elements.¶
Each resource type shall define operations possible on this resource type. This may encompass any of the mechanism defined on the HTTP transport layer and be constrained by those extensibility rules.¶
Operations shall be defined in IANA registry in a way that allows for automated processing of the operation definition, including constraints and references to other resource types.¶
FIXME: find an appropriate section for this * Compatibility Profiles - to define subsets of RPP for specific use cases or EPP compatibility.¶