feat: update API schema

abuse_whois/__init__.py

@@ -6,7 +6,13 @@
 from .errors import InvalidAddressError
 from .ip import resolve_ip_address
 from .schemas import Contact, Contacts
-from .utils import get_hostname, is_domain, is_ip_address, is_supported_address
+from .utils import (
+    get_hostname,
+    get_registered_domain,
+    is_domain,
+    is_ip_address,
+    is_supported_address,
+)
 
 try:
     import importlib.metadata as importlib_metadata
@@ -27,10 +33,12 @@ async def get_abuse_contacts(address: str) -> Contacts:
 
     hostname = get_hostname(address)
     ip_address: Optional[str] = None
+    registered_domain: Optional[str] = None
 
     shared_hosting_provider = get_shared_hosting_provider(hostname)
 
     if is_domain(hostname):
+        registered_domain = get_registered_domain(hostname)
         registrar = await get_contact_from_whois(hostname)
 
         # get IP address by domain
@@ -49,6 +57,7 @@ async def get_abuse_contacts(address: str) -> Contacts:
         address=address,
         hostname=hostname,
         ip_address=ip_address,
+        registered_domain=registered_domain,
         shared_hosting_provider=shared_hosting_provider,
         registrar=registrar,
         hosting_provider=hosting_provider,

abuse_whois/schemas/contact.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any, Literal, Optional
 
 from pydantic import Field
 
@@ -8,9 +8,11 @@
 
 
 class Contact(APIModel):
-    provider: str
-    address: str
-    type: str = Field(default="email")
+    provider: str = Field(..., description="Provider name")
+    address: str = Field(..., description="Contact address")
+    type: Literal["email", "form"] = Field(
+        "email", description="Type of contact method"
+    )
 
     def __init__(self, **data: Any):
         super().__init__(**data)
@@ -24,9 +26,15 @@ def __init__(self, **data: Any):
 
 class Contacts(APIModel):
     address: str
-    hostname: str
-    ip_address: Optional[str] = None
-
-    shared_hosting_provider: Optional[Contact] = None
-    registrar: Optional[Contact] = None
-    hosting_provider: Optional[Contact] = None
+    hostname: str = Field(..., description="Host name")
+
+    ip_address: Optional[str] = Field(None, description="IP address")
+    registered_domain: Optional[str] = Field(
+        None, description="Registered domain (a.k.a. free level domain)"
+    )
+
+    shared_hosting_provider: Optional[Contact] = Field(
+        None, description="Shared hosting provider"
+    )
+    registrar: Optional[Contact] = Field(None, description="Registrar")
+    hosting_provider: Optional[Contact] = Field(None, description="Hosting provider")

abuse_whois/utils.py

@@ -1,4 +1,5 @@
 import pathlib
+from functools import lru_cache
 from typing import Dict, List, Optional, Union, cast
 from urllib.parse import urlparse
 
@@ -8,6 +9,8 @@
 from pydantic import BaseModel, ValidationError
 from pydantic.networks import AnyHttpUrl
 
+from abuse_whois import settings
+
 
 class URLModel(BaseModel):
     url: AnyHttpUrl
@@ -61,6 +64,7 @@ def is_supported_address(v: str) -> bool:
     return False
 
 
+@lru_cache(maxsize=settings.WHOIS_LOOKUP_CACHE_SIZE)
 def get_registered_domain(v: str) -> Optional[str]:
     parsed = tldextract.extract(v)