Add support for domain research endpoint (#486)

Author: juankuquintana

README.md

@@ -92,6 +92,26 @@ domain_id = client.domains.list_domains(account_id).data[0].id
 domain = client.domains.get_domain(account_id, domain_id).data # The domain you are looking for
 ```
 
+### Research a domain
+
+> **Note:** This endpoint is part of a Private Beta. During the beta period, changes to the endpoint may occur at any time. If interested in using this endpoint, reach out to [DNSimple support](support@dnsimple.com).
+
+Research a domain name for availability and registration status information:
+
+```python
+from dnsimple import Client
+
+client = Client(access_token='a1b2c3')
+
+account_id = client.identity.whoami().data.account.id
+response = client.domains.get_domain_research_status(account_id, 'example.com')
+research = response.data
+print(research.domain)          # "example.com"
+print(research.availability)    # "unavailable"
+print(research.request_id)      # "f453dabc-a27e-4bf1-a93e-f263577ffaae"
+print(research.errors)          # []
+```
+
 ## Configuration
 
 ### Sandbox Environment

dnsimple/service/domains.py

@@ -3,9 +3,10 @@
 
 from dnsimple.response import Response
 from dnsimple.struct import Domain, Dnssec, Collaborator, DelegationSignerRecord, EmailForward, DomainPush
+from dnsimple.service.domains_research import DomainsResearch
 
 
-class Domains(object):
+class Domains(DomainsResearch):
     """
     The Domains Service handles the domains endpoint of the DNSimple API.
 

dnsimple/service/domains_research.py

@@ -0,0 +1,32 @@
+import json
+import warnings
+
+from dnsimple.response import Response
+from dnsimple.struct import DomainResearchStatus
+
+
+class DomainsResearch(object):
+    """
+    The DomainsResearch Service handles the domain research endpoint of the DNSimple API.
+    """
+
+    def get_domain_research_status(self, account_id, domain):
+        """
+        Research a domain name for availability and registration status information.
+
+        This endpoint provides information about a domain's availability status, including whether it's available for registration, already registered, or has other restrictions that prevent registration.
+
+        Note: This endpoint is part of a Private Beta. During the beta period, changes to the endpoint may occur at any time. If interested in using this endpoint, reach out to support@dnsimple.com.
+
+        See https://developer.dnsimple.com/v2/domains/research/#getDomainsResearchStatus
+
+        :param account_id: int
+            The account ID
+        :param domain: str
+            The domain name to research
+
+        :return: dnsimple.Response
+            The domain research result
+        """
+        response = self.client.get(f'/{account_id}/domains/research/status', params={'domain': domain})
+        return Response(response, DomainResearchStatus)

dnsimple/struct/__init__.py

@@ -12,6 +12,7 @@
 from dnsimple.struct.domain_price import DomainPrice
 from dnsimple.struct.domain_registration import DomainRegistration, DomainRegistrationRequest
 from dnsimple.struct.domain_renewal import DomainRenewal, DomainRenewRequest
+from dnsimple.struct.domain_research_status import DomainResearchStatus
 from dnsimple.struct.domain_restore import DomainRestore, DomainRestoreRequest
 from dnsimple.struct.domain_transfer import DomainTransfer, DomainTransferRequest
 from dnsimple.struct.domain_transfer_lock import DomainTransferLock

dnsimple/struct/domain_research_status.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+from dnsimple.struct import Struct
+
+
+@dataclass
+class DomainResearchStatus(Struct):
+    request_id = None
+    """UUID identifier for this research request"""
+    domain = None
+    """The domain name that was researched"""
+    availability = None
+    """The availability status. See https://developer.dnsimple.com/v2/domains/research/#getDomainsResearchStatus"""
+    errors = None
+    """Array of error messages if the domain cannot be registered or researched"""
+
+    def __init__(self, data):
+        super().__init__(data)

tests/service/domains_research_test.py

@@ -0,0 +1,26 @@
+import unittest
+
+import responses
+
+from dnsimple.response import Response
+from dnsimple.struct import DomainResearchStatus
+from tests.helpers import DNSimpleTest, DNSimpleMockResponse
+
+
+class DomainsResearchTest(DNSimpleTest):
+    @responses.activate
+    def test_domain_research_status(self):
+        responses.add(DNSimpleMockResponse(method=responses.GET,
+                                           path='/1010/domains/research/status?domain=taken.com',
+                                           fixture_name='getDomainsResearchStatus/success-unavailable'))
+        research = self.domains.get_domain_research_status(1010, 'taken.com').data
+
+        self.assertIsInstance(research, DomainResearchStatus)
+        self.assertEqual('25dd77cb-2f71-48b9-b6be-1dacd2881418', research.request_id)
+        self.assertEqual('taken.com', research.domain)
+        self.assertEqual('unavailable', research.availability)
+        self.assertEqual([], research.errors)
+
+
+if __name__ == '__main__':
+    unittest.main()