Network Working Group M. Wullink
Internet-Draft SIDN
Intended status: Standards Track M. Davids
Expires: October 25, 2012 R. Gieben
SIDN Labs
April 23, 2012
RESTful interface for the Extensible Provisioning Protocol
draft-wullink-restful-epp-00
Abstract
This document specifies a 'RESTful interface for EPP' (REPP) with the
aim to improve efficiency and interoperability of EPP systems.
This document includes a new EPP Protocol Extension as well as a
mapping of [RFC5730] XML-commands to an HTTP based (RESTful)
interface. Existing semantics and mappings as defined in [RFC5731],
[RFC5732] and [RFC5733] are largely retained and reusable in RESTful
EPP.
With REPP, no session is created on the EPP server. Each request
from client to server will contain all of the information necessary
to understand the request. The server will close the connection
after each HTTP request.
Status of this Memo
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 http://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 October 25, 2012.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
Wullink, et al. Expires October 25, 2012 [Page 1]
Internet-Draft REPP April 2012
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Conventions Used in This Document . . . . . . . . . . . . . . 5
4. Stateless EPP or REPP . . . . . . . . . . . . . . . . . . . . 5
5. Drawbacks Associated with Stateful EPP . . . . . . . . . . . . 6
6. EPP Extension Framework . . . . . . . . . . . . . . . . . . . 6
7. Resource Naming Convention . . . . . . . . . . . . . . . . . . 7
8. Message Exchange . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. HTTP Method Definitions . . . . . . . . . . . . . . . . . 8
8.2. REPP Request . . . . . . . . . . . . . . . . . . . . . . . 8
8.2.1. Payload Data . . . . . . . . . . . . . . . . . . . . . 8
8.2.2. Request Headers . . . . . . . . . . . . . . . . . . . 9
8.2.3. General Headers . . . . . . . . . . . . . . . . . . . 9
8.3. REPP Response . . . . . . . . . . . . . . . . . . . . . . 9
8.3.1. Response Headers . . . . . . . . . . . . . . . . . . . 9
8.3.2. General Headers . . . . . . . . . . . . . . . . . . . 10
8.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . 10
9. Interface Mapping . . . . . . . . . . . . . . . . . . . . . . 11
9.1. Hello . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.2. Password . . . . . . . . . . . . . . . . . . . . . . . . . 13
9.3. Session Management Resources . . . . . . . . . . . . . . . 13
9.3.1. Login . . . . . . . . . . . . . . . . . . . . . . . . 13
9.3.2. Logout . . . . . . . . . . . . . . . . . . . . . . . . 13
9.4. Query Resources . . . . . . . . . . . . . . . . . . . . . 13
9.4.1. Check . . . . . . . . . . . . . . . . . . . . . . . . 14
9.4.2. Info . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.4.2.1. Domain Name . . . . . . . . . . . . . . . . . . . 14
9.4.3. Poll . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.4.3.1. Poll Request . . . . . . . . . . . . . . . . . . . 15
9.4.3.2. Poll Ack . . . . . . . . . . . . . . . . . . . . . 15
9.4.4. Transfer Query Op . . . . . . . . . . . . . . . . . . 15
9.5. Object Transform Resources . . . . . . . . . . . . . . . . 16
9.5.1. Create . . . . . . . . . . . . . . . . . . . . . . . . 16
9.5.2. Delete . . . . . . . . . . . . . . . . . . . . . . . . 16
9.5.3. Renew . . . . . . . . . . . . . . . . . . . . . . . . 16
Wullink, et al. Expires October 25, 2012 [Page 2]
Internet-Draft REPP April 2012
9.5.4. Update . . . . . . . . . . . . . . . . . . . . . . . . 16
9.5.5. Transfer . . . . . . . . . . . . . . . . . . . . . . . 17
9.5.5.1. Create Op . . . . . . . . . . . . . . . . . . . . 17
9.5.5.2. Cancel Op . . . . . . . . . . . . . . . . . . . . 17
9.5.5.3. Approve Op . . . . . . . . . . . . . . . . . . . . 17
9.5.5.4. Reject Op . . . . . . . . . . . . . . . . . . . . 18
10. Transport Considerations . . . . . . . . . . . . . . . . . . . 18
11. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19
11.1. RESTful EPP XML Schema . . . . . . . . . . . . . . . . . . 20
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
13. Internationalization Considerations . . . . . . . . . . . . . 21
14. Security Considerations . . . . . . . . . . . . . . . . . . . 21
15. Obsolete EPP Result Codes . . . . . . . . . . . . . . . . . . 21
16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
16.1. Normative References . . . . . . . . . . . . . . . . . . . 22
16.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 23
A.1. X-REPP-authinfo . . . . . . . . . . . . . . . . . . . . . 23
A.1.1. Domain Info with Authorization Data . . . . . . . . . 23
A.2. Hello Example . . . . . . . . . . . . . . . . . . . . . . 24
A.2.1. RESTful <hello> Request: . . . . . . . . . . . . . . . 24
A.2.2. RESTful <hello> Response: . . . . . . . . . . . . . . 24
A.3. Password Example . . . . . . . . . . . . . . . . . . . . . 24
A.3.1. RESTful Change Password Request: . . . . . . . . . . . 24
A.3.2. RESTful Change Password Response: . . . . . . . . . . 25
A.4. Domain Create Example . . . . . . . . . . . . . . . . . . 25
A.4.1. RESTful Domain Create Request: . . . . . . . . . . . . 25
A.4.2. RESTful Domain Create Response: . . . . . . . . . . . 26
A.5. Domain Delete Example . . . . . . . . . . . . . . . . . . 26
A.5.1. RESTful Domain Delete Request: . . . . . . . . . . . . 26
A.5.2. RESTful Domain Delete Response: . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27
Wullink, et al. Expires October 25, 2012 [Page 3]
Internet-Draft REPP April 2012
1. Introduction
This document describes a new EPP Protocol Extension and a mapping of
[RFC5730] XML-commands to a [REST] interface which, in contrast to
the current EPP specification, is stateless. It aims to provide a
mechanism that is more suitable for complex, high availability
environments, as well as for environments where TCP connections can
be unreliable.
The newly defined protocol extensions described in this memo leverage
the HTTP protocol [RFC2616] and the principles of [REST]. Conforming
to the REST constraints is generally referred to as being "RESTful".
Hence we dubbed the new protocol extension: "RESTful EPP" or "REPP"
for short.
RFC 5730 [RFC5730] Section 2.1 describes that EPP can be layered over
multiple transport protocols. Currently, the EPP transport over TCP
[RFC5734] is the only widely deployed transport mapping for EPP.
This same section defines that newly defined transport mappings must
preserve the stateful nature of EPP.
With REPP, no session is created on the EPP server. Each request
from client to server will contain all of the information necessary
to understand the request. The server will close the connection
after each HTTP request.
With a stateless mechanism, some drawbacks of EPP (as mentioned in
Section 5) are circumvented.
A good understanding of the EPP base protocol specification [RFC5730]
is advised, to grasp the extension and mapping described in this
document.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. Terminology
In this document the following terminology is used.
REST - Representational State Transfer ([REST]). An architectural
style.
RESTful - A RESTful web service is a web service implemented using
HTTP and the principles of [REST].
Wullink, et al. Expires October 25, 2012 [Page 4]
Internet-Draft REPP April 2012
EPP RFCs - This is a reference to the EPP version 1.0
specifications [RFC5730], [RFC5731], [RFC5732] and [RFC5733].
Stateful EPP - The definition according to Section 2 of [RFC5730].
Stateless EPP or REPP - The RESTful EPP interface described in
this document.
URL - A Uniform Resource Locator as defined in [RFC3986].
Resource - A network data object or service that can be identified
by a URL.
Interface mapping - The mapping of [RFC5730] XML commands to
Stateless EPP.
3. Conventions Used in This Document
XML is case sensitive. Unless stated otherwise, XML specifications
and examples provided in this document MUST be interpreted in the
character case presented to develop a conforming implementation.
4. Stateless EPP or REPP
REPP is designed to solve, in the spirit of [RFC3375], the drawbacks
as mentioned in the next paragraph and yet maintain compatibility
with existing object mapping definitions.
The design intent is to provide a clear, clean and self-explanatory
interface that can easily be integrated with existing software
systems. On the basis of these principles a [REST] architectural
style was chosen. A client interacts with a REPP server via HTTP
requests.
A server implementing REPP, MUST NOT keep any client state and is not
compatible with [RFC5730], Section 2, which explicitly states that
EPP is stateful.
REPP cannot be classified as an EPP transport mapping as defined in
[RFC5730], Section 2.1. With REPP, the EPP [RFC5730] XML commands
are mapped to a REST interface and as such, RESTful EPP is regarded
as an interface mapping. Since REPP relies on a newly defined XSD
schema with protocol elements, RESTful EPP can also be referred to as
an [RFC5730], Section 2.7.1 protocol extension.
Wullink, et al. Expires October 25, 2012 [Page 5]
Internet-Draft REPP April 2012
5. Drawbacks Associated with Stateful EPP
[RFC5734] requires a stateful TCP session between a client and the
EPP server. Often this is accomplished by setting up a session with
a <login> and keeping it alive for some time before issuing a
<logout>. This may pose challenges in load-balanced environments,
when a running session for whatever reason suddenly has to be
switched from one EPP server to another and state is kept on a per
server basis.
[RFC5734] EPP sessions can wind up in a state where they are no
longer linked to an active TCP connection, especially in an
environment where TCP connectivity is flaky. This may raise problems
in situations where session limits are enforced.
REPP is designed to avoid these drawbacks, hence making the
interaction between an EPP client and an EPP server more robust and
efficient.
6. EPP Extension Framework
According to [RFC3735], Section 2, EPP provides an extension
framework that allows features to be added at the protocol, object,
and command-response levels. RESTful EPP (REPP) affects the
following levels:
Protocol extension: RESTful EPP defines a new namespace
"urn:ietf:params:xml:ns:restful-epp-1.0". It declares new
elements, which MUST be used for RESTful EPP. The root element
for the new namespace is the <rest> element. This element MUST
contain an object mapping defined by the object mapping schemas.
Object extension: RESTful EPP does not define any new object level
extensions. The existing object level extensions can be reused.
However, any existing object mapping element, including any added
extension elements it might contain, SHALL be added as a child to
the new <rest> element.
Command-Response extension: RESTful EPP does not use the "command"
concept, because the 'command' concept is part of a RPC style and
not a RESTful style. A REST URL and HTTP method combination have
replaced the command structure. All command extensions can be
reused as a rest extension.
RESTful EPP reuses the existing response messages defined in the
EPP RFCs. The EPP response MUST be added to the standard <epp>
element and SHALL NOT be part of any <rest> element.
Wullink, et al. Expires October 25, 2012 [Page 6]
Internet-Draft REPP April 2012
The DNSSEC [RFC5910], E.164 number [RFC4114] and ENUM validation
information [RFC5076] extension mapping elements can be added as
children of the <rest> element.
7. Resource Naming Convention
A resource can be a single unique object identifier e.g. a domain
name, or a collection of objects. The complete set of objects a
client can use in registry operations MUST be identified by {context-
root}/{version}/{collection}
o {context-root} is the base URL which MUST be specified by each
registry.
o {version} is a label which identifies the interface version. This
is the equivalent of the <version> element in the EPP RFCs.
o {collection} MUST be substituted by "domains", "hosts" or
"contacts", referring to either [RFC5731], [RFC5732] or [RFC5733].
o A trailing slash MAY be added to each request. Implementations
MUST consider requests which only differ with respect to this
trailing slash as identical.
A specific object instance MUST be identified by {context-root}/
{version}/{collection}/{id} where {id} is a unique object identifier
described in EPP RFCs.
An example domain name resource following this naming convention,
would look like this:
/rest/v1/domains/example.com
The level below a collection MUST be used to identify a object
instance, the level below an object instance MUST be used to identify
attributes of the object instance.
With RESTful EPP the object identifiers are embedded in URLs. This
makes any object identifier in the request messages superfluous.
However, since the goal of RESTful EPP is to stay compatible with the
existing EPP object mapping schemas, this redundancy is accepted as a
trade off. Removing the object identifier from the request message
would require new object mapping schemas.
The server MUST return HTTP Status-Code 412 when the object
identifier (for example <domain:name>, <host:name> or <contact:id>)
in the HTTP message-body does not match the {id} object identifier in
Wullink, et al. Expires October 25, 2012 [Page 7]
Internet-Draft REPP April 2012
the URL.
8. Message Exchange
A [RFC5730] request includes a command- and object mapping to which a
command must be applied. With RESTful EPP, some of the request
messages are expressed by a combination of a resource and an HTTP
method.
Data (payload) belonging to a request is put into the HTTP message-
body or into an HTTP request-header, depending on the nature of the
request as defined in Section 9.
An HTTP request MUST contain no more than one EPP message. HTTP
requests MUST be processed independently of each other and in the
same order as the server receives them.
8.1. HTTP Method Definitions
The operations on resources MUST be performed by an HTTP method. The
server MUST support the following "verbs" ([REST]).
GET: Request a representation of a resource or a collection of
resources.
PUT: Update an existing resource.
POST: Create a new resource.
DELETE: Delete an existing resource.
HEAD: Check for the existence of a resource.
OPTIONS: Request a greeting.
8.2. REPP Request
8.2.1. Payload Data
The payload data of a RESTful EPP request can be transmitted to the
server using the POST, PUT and GET HTTP methods.
POST and PUT: Payload data, when required, MUST be added to the
message-body.
Wullink, et al. Expires October 25, 2012 [Page 8]
Internet-Draft REPP April 2012
GET: When payload data is required, it concerns <authInfo>. This
SHALL be put in the "X-REPP-authinfo" HTTP request-header.
8.2.2. Request Headers
HTTP request-headers are used to transmit additional or optional
request data to the server. All RESTful EPP HTTP headers must have
the "X-REPP-" prefix.
X-REPP-cltrid: The client transaction identifier is the equivalent
of the <clTRID> element in the EPP RFCs and MUST be used
accordingly. When this header is present in a client request, an
equivalent element in the message-body MAY also be present, but
MUST than be consistent with the header.
X-REPP-authinfo: The X-REPP-authinfo request-header is the
alternative of the <authInfo> element in the EPP RFCs and MUST be
used accordingly. It MUST contain the entire authorization
information element as mentioned in Section 11.1.
8.2.3. General Headers
General-headers MAY be used as defined in HTTP/1.1 [RFC2616]. For
REPP, the following general-headers are REQUIRED in HTTP requests.
Accept-Language: This request-header is equivalent to the <lang>
element in the EPP <login> command, expect that the usage of this
header by the client is OPTIONAL. The server MUST support the use
of HTTP Accept-Language header in client requests. The client MAY
issue a <hello> to discover the languages known by the server.
Multiple servers in a load-balanced environment SHOULD reply with
consistent <lang> elements in a <greeting>. Clients SHOULD NOT
expect that obtained <lang> information remains consistent between
different requests. Languages not supported by the server default
to "en".
8.3. REPP Response
The server response is made up out of a HTTP Status-Code, HTTP
response-headers and it MAY contain an EPP XML message in the HTTP
message-body.
8.3.1. Response Headers
HTTP response-headers are used to transmit additional response data
to the client. All RESTful EPP HTTP headers must have the "X-REPP-"
prefix.
Wullink, et al. Expires October 25, 2012 [Page 9]
Internet-Draft REPP April 2012
X-REPP-svtrid: This header is the equivalent of the <svTRID> element
in the EPP RFCs and MUST be used accordingly. If an HTTP message-
body with the EPP XML equivalent <svTRID> exists, both values MUST
be consistent.
X-REPP-cltrid: This header is the equivalent of the <clTRID> element
in the EPP RFCs and MUST be used accordingly. If an HTTP message-
body with the EPP XML equivalent <clTRID> exists, both values MUST
be consistent.
X-REPP-eppcode: This header is the equivalent of the <result code>
element in te EPP RFCs and MUST be used accordingly.If an HTTP
message-body with The EPP XML equivalent <result code> exists,
both values MUST be consistent.
X-REPP-avail: The EPP avail header is the alternative of the "avail"
attribute of the <object:name> element in a check response and
MUST be used accordingly.
8.3.2. General Headers
General-headers MAY be used as defined in HTTP/1.1 [RFC2616]. For
REPP, the following general-headers are REQUIRED in HTTP responses.
Cache-Control: This general-header... [TBD: the idea is to prohibit
caching. Even though it will probably work and be useful in some
scenario's, it also complicates matters.]
Connection: The server MUST add the "Connection: close" general-
header to each HTTP response.
8.4. Error Handling
RESTful EPP is designed atop of the HTTP protocol, both are an
application layer protocol with their own status- and result codes.
The value of an EPP result code and HTTP Status-Code MUST remain
independent of each other. E.g. an EPP result code indicating an
error can be combined with an HTTP request with Status-Code 200.
HTTP Status-Code: MUST only return status information related to the
HTTP protocol, When there is a mismatch between the object
identifier in the HTTP message-body and the resource URL HTTP
Status-Code 412 MUST be returned.
The following EPP result codes specify an interface-,
authorization-, authentication- or an internal server error and
MUST NOT be used in RESTful EPP. Instead, when the related error
occurs, an HTTP Status-Code MUST be returned in accordance to the
Wullink, et al. Expires October 25, 2012 [Page 10]
Internet-Draft REPP April 2012
mapping shown in Table 1.
EPP result code: MUST only return EPP result information relating to
the EPP protocol. The HTTP header "X-REPP-eppcode" MUST be used
for EPP result code information.
EPP result code and HTTP Status-Code mapping.
+----------------------------------------+------------------+
| EPP result code | HTTP Status-Code |
+----------------------------------------+------------------+
| 2000 unknown command | 400 |
| 2201 authorization error | 401 |
| 2202 Invalid authorization information | 401 |
| 2101 unimplemented command | 501 |
+----------------------------------------+------------------+
Table 1
9. Interface Mapping
This section describes the details of the REST interface by referring
to the [RFC5730] Section 2.9 Protocol Commands and defining how these
are mapped to a REST request.
Each RESTful operation consists of four parts: 1) the resource, 2)
the HTTP method 3) the request payload, which is the HTTP message-
body of the request, 4) the response payload, being the HTTP message-
body of the response.
The following table lists them all and the subsequent sections
provide details for each request. Each URL in the table is prefixed
with "/rest/v1/". To make the table fit we use the following
abbreviations:
{c}: An abbreviation for {collection}: this MUST be substituted with
"domains", "hosts", "contacts" or "messages".
{i}: An abbreviation for {id}: a domain name, host name, contact id
or a message id.
(opt): The item is optional.
Wullink, et al. Expires October 25, 2012 [Page 11]
Internet-Draft REPP April 2012
Command mapping from Stateful EPP to Stateless EPP.
+---------------+-------------------+----------------+--------------+
| EPP command | RESTful EPP | Request | Response |
| | resource | payload | payload |
+---------------+-------------------+----------------+--------------+
| Hello | OPTIONS / | N/A | <greeting> |
| Login | N/A | N/A | N/A |
| Logout | N/A | N/A | N/A |
| Check | HEAD {c}/{i} | N/A | N/A |
| Info | GET {c}/{i} | AUTH(opt) | <info> |
| Poll request | GET messages | N/A | <poll> |
| Poll ack | DELETE | N/A | <poll> ack |
| | messages/{i} | | |
| Transfer | GET | AUTH(opt) | <transfer> |
| (query) | {c}/{i}/transfer | | |
| New password | PUT password | password | N/A |
| Create | POST {c} | <create> | <create> |
| Delete | DELETE {c}/{i} | N/A | <delete> |
| Renew | PUT | <renew> | <renew> |
| | {c}/{i}/validity | | |
| Transfer | POST | <transfer> | <transfer> |
| (create) | {c}/{i}/transfer | | |
| Transfer | DELETE | N/A | <transfer> |
| (cancel) | {c}/{i}/transfer | | |
| Transfer | PUT | N/A | <transfer> |
| (approve) | {c}/{i}/transfer | | |
| Transfer | DELETE | N/A | <transfer> |
| (reject) | {c}/{i}/transfer | | |
| Update | PUT {c}/{i} | <update> | <update> |
+---------------+-------------------+----------------+--------------+
Table 2
9.1. Hello
o Request: OPTIONS /
o Request payload: N/A
o Response payload: <greeting>
The <greeting> (Section 2.4 RFC 5730) MUST NOT be automatically
transmitted by the server with each new HTTP connection. The server
MUST send a <greeting> element in response to a OPTIONS method on the
root "/" resource.
A stateless EPP client MUST NOT use a <hello> XML payload.
Wullink, et al. Expires October 25, 2012 [Page 12]
Internet-Draft REPP April 2012
9.2. Password
o Request: PUT password/
o Request payload: New password
o Response payload: N/A
The client MUST use the HTTP PUT method on the password resource.
This is the equivalent of the <newPW> element in the <login> command
described in [RFC5730]. The request message-body MUST contain the
new password which MUST be encoded using Base64 [RFC4648].
After a successful password change, the HTTP header "X-REPP-eppcode"
must contain EPP result code 1000, otherwise an appropriate 2xxx
range EPP result code.
9.3. Session Management Resources
The server MUST NOT create a client session. Login credentials MUST
be added to each client request. This SHOULD be done with any of the
well known HTTP authentication mechanisms. Basic authentication MAY
be used but MUST be combined with TLS [RFC5246] for added security.
To protect information exchanged between an EPP client and an EPP
server [RFC5734] Section 9 level of security is REQUIRED.
9.3.1. Login
The <login> command MUST NOT be implemented by a server. The <newPW>
element has been replaced by the Password resource. The <lang>
element has been replaced by the Accept-Language HTTP request-header.
The <svcs> element has no equivalent in RESTful EPP, the client can
use a <hello> to discover the server supported namespace URIs. The
server MUST check every XML namespace used in client XML requests.
An unsupported namespace MUST result in the appropriate EPP result
code.
9.3.2. Logout
The <logout> command MUST NOT be implemented by the server. The
server MUST add the "Connection: close" HTTP general-header to each
response.
9.4. Query Resources
Wullink, et al. Expires October 25, 2012 [Page 13]
Internet-Draft REPP April 2012
9.4.1. Check
o Request: HEAD {collection}/{id}
o Request payload: N/A
o Response payload: N/A
The HTTP header X-REPP-avail with a value of "1" or "0" is returned,
depending on whether the object can be provisioned or not.
A <check> request MUST be limited to checking only one resource {id}
at a time. This may seem a step backwards when compared to the check
command defined in the object mapping of the EPP RFCs where multiple
object-ids are allowed inside a check command. The RESTful version
of the check is however more efficient.
The server MUST NOT support any <object:reason> elements described in
the EPP object mapping RFCs.
9.4.2. Info
o Request: GET {collection}/{id}
o Request payload: OPTIONAL X-REPP-authinfo HTTP header with
<authInfo>.
o Response payload: Object <info> response.
A object <info> request MUST be performed with the HTTP GET method on
a resource identifying an object instance. The response MUST be a
response message as described in object mapping of the EPP RFCs,
possibly extended with an [RFC3915] extension element (<rgp:
infData>).
9.4.2.1. Domain Name
A domain name <info> differs from a contact- and host <info> in the
sense that EPP Domain Name Mapping [RFC5731], Section 3.1.2 describes
an OPTIONAL "hosts" attribute for the <domain:name> element. This
attribute is mapped to additional REST resources to be used in a
domain name info request.
The specified default value is "all". This default is mapped to a
shortcut, the resource object instance URL without any additional
labels.
Wullink, et al. Expires October 25, 2012 [Page 14]
Internet-Draft REPP April 2012
o default: GET domains/{id}
o Hosts=all: GET domains/{id}/all
o Hosts=del: GET domains/{id}/del
o Hosts=sub: GET domains/{id}/sub
o Hosts=none: GET domains/{id}/none
The server MAY require the client to include additional authorization
information. The authorization data MUST be sent with the "X-REPP-
authinfo" HTTP request-header.
9.4.3. Poll
9.4.3.1. Poll Request
o Request: GET messages/
o Request payload: N/A
o Response payload: Poll request response message.
A client MUST use the HTTP GET method on the messages collection to
request the message at the head of the queue.
9.4.3.2. Poll Ack
o Request: DELETE messages/{id}
o Request payload: N/A
o Response payload: Poll ack response message
A client MUST use the HTTP DELETE method on a message instance to
remove the message from the message queue.
9.4.4. Transfer Query Op
o Request: GET {collection}/{id}/transfer
o Request payload: Optional X-REPP-authinfo HTTP header with
<authInfo>
o Response payload: Transfer query response message.
A <transfer> query MUST be performed with the HTTP GET method on the
Wullink, et al. Expires October 25, 2012 [Page 15]
Internet-Draft REPP April 2012
transfer resource of a specific object instance.
9.5. Object Transform Resources
9.5.1. Create
o Request: POST {collection}/
o Request payload: Object <create>.
o Response payload: Object <create> response.
A client MUST create a new object with the HTTP POST method in
combination with an object collection.
9.5.2. Delete
o Request: DELETE {collection}/{id}
o Request payload: N/A
o Response payload: Object <delete> response.
Deleting an object from the registry database MUST be performed with
the HTTP DELETE method on a REST resource specifying a specific
object instance.
9.5.3. Renew
o Request: PUT {collection}/{id}/validity
o Request payload: Object <renew>.
o Response payload: Object <renew> response.
Renewing an object is only specified by [RFC5731], the <renew>
command has been mapped to a validity resource.
9.5.4. Update
o Request: PUT {collection}/{id}
o Request payload: Object:update.
o Response payload: Update response message
An object <update> request MUST be performed with the HTTP PUT method
on a specific object resource. The payload MUST contain an <object:
Wullink, et al. Expires October 25, 2012 [Page 16]
Internet-Draft REPP April 2012
update> described in the EPP RFCs, possibly extended with [RFC3915]
<update> extension elements.
9.5.5. Transfer
Transferring an object from one sponsoring client to another is only
specified in [RFC5731] and [RFC5733]. The <transfer> command has
been mapped to a transfer resource.
The semantics of the HTTP DELETE method are determined by the role of
the client executing the method. For the current sponsoring
registrar the DELETE method is defined as "reject transfer". For the
new sponsoring registrar the DELETE method is defined as "cancel
transfer".
9.5.5.1. Create Op
o Request: POST {collection}/{id}/transfer
o Request payload: <object:transfer>.
o Response Payload: Transfer start response.
Initiating a transfer MUST be done by creating a new "transfer"
resource with the HTTP POST method on a specific domain name or
contact object instance. The server MAY require authorization
information to validate the transfer request.
9.5.5.2. Cancel Op
o Request: DELETE {collection}/{id}/transfer
o Request payload: N/A
o Response payload: Transfer cancel response message.
The new sponsoring client MUST use the HTTP DELETE method to cancel a
requested transfer.
9.5.5.3. Approve Op
o Request: PUT {collection}/{id}/transfer
o Request payload: N/A
o Response payload: Transfer approve response message.
The current sponsoring client MUST use the HTTP PUT method to approve
Wullink, et al. Expires October 25, 2012 [Page 17]
Internet-Draft REPP April 2012
a transfer requested by the new sponsoring client.
9.5.5.4. Reject Op
o Request: DELETE {collection}/{id}/transfer
o Request payload: N/A
o Response payload: Transfer reject response message
The current sponsoring client MUST use the HTTP DELETE method to
reject a transfer requested by the new sponsoring client.
10. Transport Considerations
Section 2.1 of the EPP core protocol specification [RFC5730]
describes considerations to be addressed by protocol transport
mappings. This document addresses each of the considerations using a
combination of features described in this document and features
provided by HTTP as follows:
o HTTP is an application layer protocol which uses TCP as a
transport protocol. TCP includes features to provide reliability,
flow control, ordered delivery, and congestion control. Section
1.5 of RFC 793 describes these features in detail; congestion
control principles are described further in RFC 2581 and RFC 2914.
HTTP is a stateless protocol and as such it does not maintain any
client state or session.
o The stateful nature of EPP is no longer preserved through managed
sessions. There still is a controlled message exchanges because
HTTP uses TCP as transport layer protocol.
o HTTP 1.1 allows persistent connections which can be used to send
multiple HTTP requests to the server using the same connection.
The server MUST NOT allow persistent connections.
o The server MUST NOT allow pipelining and return EPP result code
2002 if pipelining is detected.
o Batch-oriented processing (combining multiple EPP commands in a
single HTTP request) MUST NOT be permitted.
o Section 8 of this document describes features to frame EPP request
data by adding the data to an HTTP request message-body or
request-header.
Wullink, et al. Expires October 25, 2012 [Page 18]
Internet-Draft REPP April 2012
o A request processing failure has no influence on the processing of
other requests. The stateless nature of the server allows a
client to retry a failed request or send another request.
11. Formal Syntax
The extension used by RESTful EPP is specified in XML Schema
notation. The formal syntax presented here is a complete schema
representation of RESTful EPP suitable for automated validation of
EPP XML instances. The schema is based on the XML schemas defined in
[RFC5730]. [RFC3735] Section 2.3 states that it MUST be announced in
the <greeting> element.
Wullink, et al. Expires October 25, 2012 [Page 19]
Internet-Draft REPP April 2012
11.1. RESTful EPP XML Schema
The RESTful EPP Schema.
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns:repp="urn:ietf:params:xml:ns:restful-epp-1.0"
xmlns:epp="urn:ietf:params:xml:ns:epp-1.0"
xmlns:eppcom="urn:ietf:params:xml:ns:eppcom-1.0"
xmlns="HTTP://www.w3.org/2001/XMLSchema"
targetNamespace="urn:ietf:params:xml:ns:restful-epp-1.0"
elementFormDefault="qualified">
<!-- Import common element types. -->
<import namespace="urn:ietf:params:xml:ns:eppcom-1.0"
schemaLocation="eppcom-1.0.xsd"/>
<import namespace="urn:ietf:params:xml:ns:epp-1.0"
schemaLocation="epp-1.0.xsd"/>
<annotation>
<documentation>
RESTful EPP schema.
</documentation>
</annotation>
<!-- The rest element should be used as extension root. -->
<element name="rest" type="epp:extAnyType"/>
<!-- A request which requires auth info can use this
authorization shortcut without an object id. -->
<element name="authorization" type="re:authInfoType"/>
<!-- The authinfo element. For use with domain and host info
and domain transfer. -->
<complexType name="authInfoType">
<choice>
<element name="pw" type="eppcom:pwAuthInfoType"/>
<element name="ext" type="eppcom:extAuthInfoType"/>
</choice>
</complexType>
</schema>
Figure 1
Wullink, et al. Expires October 25, 2012 [Page 20]
Internet-Draft REPP April 2012
12. IANA Considerations
[TBD: This draft defines three resource collections; domains,
contacts, hosts. This may require an IANA RESTful EPP collection
protocol registry. RFC3688 defines an IANA XML Registry and
'restful-epp-1.0' defined here would have to be added to that:
http://www.iana.org/assignments/xml-registry-index.html ]
13. Internationalization Considerations
[TBD: Do we need them? ]
14. Security Considerations
RFC 5730 describes a <login> command for transmitting client
credentials. This command MUST NOT be used for RESTful EPP. Due to
the stateless nature of REST clients MUST transmit their credentials
with each request. The validation of the user credentials must be
performed by an out-of-band mechanism. This could be done with Basic
and Digest access authentication [RFC2617] or with the use of OAuth
[RFC5849].
EPP does not use XML encryption to protect messages. Furthermore,
RESTful EPP HTTP servers are vulnerable to common denial-of-service
attacks. Therefore, the security considerations of [RFC5734] also
apply to RESTful EPP.
15. Obsolete EPP Result Codes
The following result codes specified in [RFC5730] are no longer
meaningful in RESTful EPP and MUST NOT be used.
+------+------------------------------------------------------------+
| Code | Reason |
+------+------------------------------------------------------------+
| 1500 | The logout command is not used anymore. |
| 2002 | Commands can now be sent in any order. |
| 2100 | The protocol version is embedded in the base URL of the |
| | interface. |
| 2200 | The login command is not used anymore. |
+------+------------------------------------------------------------+
16. References
Wullink, et al. Expires October 25, 2012 [Page 21]
Internet-Draft REPP April 2012
16.1. Normative References
[REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", 2000.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[RFC3915] Hollenbeck, S., "Domain Registry Grace Period Mapping for
the Extensible Provisioning Protocol (EPP)", RFC 3915,
September 2004.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
STD 69, RFC 5730, August 2009.
[RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Domain Name Mapping", STD 69, RFC 5731, August 2009.
[RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Host Mapping", STD 69, RFC 5732, August 2009.
[RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Contact Mapping", STD 69, RFC 5733, August 2009.
[RFC5734] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
Transport over TCP", STD 69, RFC 5734, August 2009.
16.2. Informative References
[RFC3375] Hollenbeck, S., "Generic Registry-Registrar Protocol
Requirements", RFC 3375, September 2002.
[RFC3735] Hollenbeck, S., "Guidelines for Extending the Extensible
Wullink, et al. Expires October 25, 2012 [Page 22]
Internet-Draft REPP April 2012
Provisioning Protocol (EPP)", RFC 3735, March 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4114] Hollenbeck, S., "E.164 Number Mapping for the Extensible
Provisioning Protocol (EPP)", RFC 4114, June 2005.
[RFC5076] Hoeneisen, B., "ENUM Validation Information Mapping for
the Extensible Provisioning Protocol", RFC 5076,
December 2007.
[RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849,
April 2010.
[RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS)
Security Extensions Mapping for the Extensible
Provisioning Protocol (EPP)", RFC 5910, May 2010.
Appendix A. Examples
In these examples, lines starting with "C:" represent data sent by a
protocol client and lines starting with "S:" represent data returned
by a REPP protocol server. Indentation and white space in examples
are provided only to illustrate element relationships and are not
REQUIRED features of this protocol.
A.1. X-REPP-authinfo
A.1.1. Domain Info with Authorization Data
The X-REPP-authinfo header in a Domain Info Request might look like
this:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
<extension>
<re:rest xmlns:re="urn:ietf:params:xml:ns:restful-epp-1.0">
<re:authorization>
<re:pw>passwordfordomain</re:pw>
</re:authorization>
</re:rest>
</extension>
</epp>
So this HTTP header MUST contain the entire authorization information
Wullink, et al. Expires October 25, 2012 [Page 23]
Internet-Draft REPP April 2012
element as mentioned in Section 11.1.
A.2. Hello Example
A.2.1. RESTful <hello> Request:
C: OPTIONS /rest/v1/ HTTP/1.1
C: Host: repp.example.com
C: Cache-Control: no-cache
C: Authorization: Basic amRvZTp0ZXN0
C: Pragma: no-cache
C: Accept: application/epp+xml
C: Accept-Encoding: gzip,deflate
C: Accept-Language: en
C: Accept-Charset: utf-8
A.2.2. RESTful <hello> Response:
S: HTTP/1.1 200 OK
S: Date: Sun, 10 Apr 2012 12:00:00 UTC
S: Server: Acme REPP server v1.0
S: Content-Length: 799
S: Content-Type: application/epp+xml
S: Connection: close
S:
S: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
S: <greeting>
S: <!-- rest of the greeting elements -->
S: </greeting>
S: </epp>
A.3. Password Example
A.3.1. RESTful Change Password Request:
C: PUT /rest/v1/password/ HTTP/1.1
C: Host: repp.example.com
C: Cache-Control: no-cache
C: Authorization: Basic amRvZTp0ZXN0
C: Pragma: no-cache
C: Accept-Language: en
C: Accept-Charset: utf-8
C: X-REPP-cltrid: ABC-12345
C: Content-Type: text/plain
C: Content-Length: 44
C:
C: bWFpbG1lYXQ6bWFhcnRlbi53dWxsaW5rQHNpZG4ubmw=
Wullink, et al. Expires October 25, 2012 [Page 24]
Internet-Draft REPP April 2012
A.3.2. RESTful Change Password Response:
S: HTTP/1.1 200 OK
S: Date: Sun, 10 Apr 2012 12:00:00 UTC
S: Server: Acme REPP server v1.0
S: Content-Language: en
S: Content-Length: 0
S: X-REPP-cltrid: ABC-12345
S: X-REPP-svtrid: 54321-XYZ
S: X-REPP-eppcode: 1000
S: Connection: close
A.4. Domain Create Example
A.4.1. RESTful Domain Create Request:
C: POST /rest/v1/domains/ HTTP/1.1
C: Host: repp.example.com
C: Cache-Control: no-cache
C: Authorization: Basic amRvZTp0ZXN0
C: Pragma: no-cache
C: Accept-Language: en
C: Accept-Charset: utf-8
C: Accept: application/epp+xml
C: X-REPP-cltrid: ABC-12345
C: Content-Type: text/plain
C: Content-Length: 543
C: <?xml version="1.0" encoding="UTF-8" standalone="no"?>
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0">
C: <extension>
C: <re:rest xmlns:re="urn:ietf:params:xml:ns:restful-epp-1.0">
C: <domain:create>
C: <!-- Object specific elements-->
C: </domain:create>
C: </re:rest>
C: </extension>
C: </epp>
Wullink, et al. Expires October 25, 2012 [Page 25]
Internet-Draft REPP April 2012
A.4.2. RESTful Domain Create Response:
S: HTTP/1.1 200 OK
S: Date: Sun, 10 Apr 2012 12:00:00 UTC
S: Server: Acme REPP server v1.0
S: Content-Language: en
S: Content-Length: 642
S: X-REPP-cltrid: ABC-12345
S: X-REPP-svtrid: 54321-XYZ
S: X-REPP-eppcode: 1000
S: Content-Type: application/epp+xml
S: Connection: close
S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0">
S: <response>
S: <result code="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <domain:creData
S: <!-- Object specific elements-->
S: </domain:creData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>
A.5. Domain Delete Example
A.5.1. RESTful Domain Delete Request:
C: DELETE /rest/v1/domains/example.com HTTP/1.1
C: Host: repp.example.com
C: Cache-Control: no-cache
C: Authorization: Basic amRvZTp0ZXN0
C: Pragma: no-cache
C: Accept-Language: en
C: Accept-Charset: utf-8
C: X-REPP-cltrid: ABC-12345
Wullink, et al. Expires October 25, 2012 [Page 26]
Internet-Draft REPP April 2012
A.5.2. RESTful Domain Delete Response:
S: HTTP/1.1 200 OK
S: Date: Sun, 10 Apr 2012 12:00:00 UTC
S: Server: Acme REPP server v1.0
S: Content-Language: en
S: Content-Length: 505
S: X-REPP-cltrid: ABC-12345
S: X-REPP-svtrid: 54321-XYZ
S: X-REPP-eppcode: 1000
S: Content-Type: application/epp+xml
S: Connection: close
S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0">
S: <response>
S: <result code="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>
Authors' Addresses
Maarten Wullink
SIDN
Meander 501
Arnhem, 6825 MD
NL
Phone: +31 26 3525555
Email: maarten.wullink@sidn.nl
URI: https://sidn.nl/
Wullink, et al. Expires October 25, 2012 [Page 27]
Internet-Draft REPP April 2012
Marco Davids
SIDN Labs
Meander 501
Arnhem, 6825 MD
NL
Phone: +31 26 3525555
Email: marco.davids@sidn.nl
URI: https://sidn.nl/
R. (Miek) Gieben
SIDN Labs
Meander 501
Arnhem, 6825 MD
NL
Phone: +31 26 3525555
Email: miek.gieben@sidn.nl
URI: https://sidn.nl/
Wullink, et al. Expires October 25, 2012 [Page 28]