From b2ac17a75872cbb0106ee5c316f1953af9172ef2 Mon Sep 17 00:00:00 2001
From: Ole Michaelis <Ole.Michaelis@googlemail.com>
Date: Mon, 19 Feb 2024 10:45:56 +0100
Subject: [PATCH] Document Domain Restore with examples (#565)

---
 content/v2/registrar.markdown                 | 96 +++++++++++++++++++
 fixtures/v2/api/getDomainRestore/success.http | 19 ++++
 fixtures/v2/api/restoreDomain/success.http    | 19 ++++
 3 files changed, 134 insertions(+)
 create mode 100644 fixtures/v2/api/getDomainRestore/success.http
 create mode 100644 fixtures/v2/api/restoreDomain/success.http

diff --git a/content/v2/registrar.markdown b/content/v2/registrar.markdown
index 2b372242..d0f01c90 100644
--- a/content/v2/registrar.markdown
+++ b/content/v2/registrar.markdown
@@ -541,6 +541,102 @@ Responds with HTTP 200 on success.
 
 Responds with [HTTP 401](/v2#unauthorized) in case of authentication issues.
 
+## Restore a domain {#restoreDomain}
+
+    POST /:account/registrar/domains/:domain/restores
+
+Restore a eligable expired domain name where your registration with DNSimple lapsed.
+
+Your account must be active for this command to complete successfully.
+You will be automatically charged the restore fee upon successful restore, so please be careful with this command.
+
+### Parameters
+
+Name | Type | Description
+-----|------|------------
+`:account` | `integer` | The account id
+`:domain` | `string` | The domain name
+
+### Example
+
+Restore the domain `example.com` in the account `1010`:
+
+    curl  -H 'Authorization: Bearer <token>' \
+          -H 'Accept: application/json' \
+          -H 'Content-Type: application/json' \
+          -X POST \
+          https://api.dnsimple.com/v2/1010/registrar/domains/example.com/restores
+
+### Input
+
+Name | Type | Description
+-----|------|------------
+`premium_price` | `string` | **Required** as confirmation of the price, only if the domain is premium.
+
+##### Example with optional premium_price
+
+~~~json
+{
+  "premium_price": '109.00'
+}
+~~~
+
+### Response
+
+Responds with HTTP 201 when restore was processed and completed.
+
+Responds with HTTP 202 when restore was processed but is pending completion.
+
+~~~json
+<%= pretty_print_fixture("/api/restoreDomain/success.http") %>
+~~~
+
+### Errors
+
+Responds with [HTTP 400](/v2#bad-request) if the domain cannot be restored.
+
+Responds with [HTTP 401](/v2#unauthorized) in case of authentication issues.
+
+Responds with [HTTP 402](/v2#payment-required) if the account has outstanding payments.
+
+## Retrieve a Domain Restore {#getDomainRestore}
+
+Retrieves the details of an existing domain restore.
+
+~~~
+GET /:account/registrar/domains/:domain/restores/:domain_restore
+~~~
+
+### Parameters
+
+Name | Type | Description
+-----|------|------------
+`:account` | `integer` | The account id
+`:domain` | `string` | The domain name
+`:domain_restore` | `integer` | The domain restore id
+
+### Example
+
+Get the domain restore with ID `1` in the account `1010` for the domain `example.com`:
+
+~~~
+curl  -H 'Authorization: Bearer <token>' \
+      -H 'Accept: application/json' \
+      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/restores/1
+~~~
+
+### Response
+
+Responds with HTTP 200 on success.
+
+~~~json
+<%= pretty_print_fixture("/api/getDomainRestore/success.http") %>
+~~~
+
+### Errors
+
+Responds with [HTTP 401](/v2#unauthorized) in case of authentication issues.
+
 ## Authorize a domain transfer out {#authorizeDomainTransferOut}
 
     POST /:account/registrar/domains/:domain/authorize_transfer_out
diff --git a/fixtures/v2/api/getDomainRestore/success.http b/fixtures/v2/api/getDomainRestore/success.http
new file mode 100644
index 00000000..8bb3a81b
--- /dev/null
+++ b/fixtures/v2/api/getDomainRestore/success.http
@@ -0,0 +1,19 @@
+HTTP/1.1 200 OK
+Server: nginx
+Date: Sun, 18 Feb 2024 10:48:05 GMT
+Content-Type: application/json
+Content-Length: 120
+Connection: keep-alive
+X-WORK-WITH-US: Love automation? So do we! https://dnsimple.com/jobs
+Cache-Control: no-cache
+X-Request-Id: 2a8d691f-f47e-4d41-9916-eba67e683914
+X-Runtime: 0.004845
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+X-Download-Options: noopen
+X-Permitted-Cross-Domain-Policies: none
+Content-Security-Policy: frame-ancestors 'none'
+Strict-Transport-Security: max-age=63072000
+
+{"data":{"id":43,"domain_id":214,"state":"new","created_at":"2024-02-14T14:40:42Z","updated_at":"2024-02-14T14:40:42Z"}}
\ No newline at end of file
diff --git a/fixtures/v2/api/restoreDomain/success.http b/fixtures/v2/api/restoreDomain/success.http
new file mode 100644
index 00000000..1ff0efa4
--- /dev/null
+++ b/fixtures/v2/api/restoreDomain/success.http
@@ -0,0 +1,19 @@
+HTTP/1.1 201 Created
+Server: nginx
+Date: Sun, 18 Feb 2024 10:46:17 GMT
+Content-Type: application/json
+Content-Length: 120
+Connection: keep-alive
+X-WORK-WITH-US: Love automation? So do we! https://dnsimple.com/jobs
+Cache-Control: no-cache
+X-Request-Id: 3bf33ae7-22f2-473c-8e39-8738d2bcce89
+X-Runtime: 0.006332
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+X-Download-Options: noopen
+X-Permitted-Cross-Domain-Policies: none
+Content-Security-Policy: frame-ancestors 'none'
+Strict-Transport-Security: max-age=63072000
+
+{"data":{"id":43,"domain_id":214,"state":"new","created_at":"2024-02-14T14:40:42Z","updated_at":"2024-02-14T14:40:42Z"}}
\ No newline at end of file