feat: add a generic API request interface (#384)

# Description

Adds a generic API request interface to make arbitrary API requests.
<!-- Please provide a general summary of your PR changes and link any
related issues or other pull requests. -->

# Testing

<!-- 
Please provide details on how you tested this code. See below.

- All pull requests must be tested (unit tests where possible with
accompanying cassettes, or provide a screenshot of end-to-end testing
when unit tests are not possible)
- New features must get a new unit test
- Bug fixes/refactors must re-record existing cassettes 
-->

# Pull Request Type

Please select the option(s) that are relevant to this PR.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Improvement (fixing a typo, updating readme, renaming a variable
name, etc)

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v10.6.0 (2026-02-25)
+
+- Adds generic `make_api_call` function
+
 ## v10.5.1 (2026-02-24)
 
 - Corrects the return type of `carrier_account.all()` (closes #386)

easypost/constant.py

@@ -1,6 +1,6 @@
 # flake8: noqa
 # Library version
-VERSION = "10.5.1"
+VERSION = "10.6.0"
 VERSION_INFO = [str(number) for number in VERSION.split(".")]
 
 # Client defaults

easypost/easypost_client.py

@@ -1,11 +1,15 @@
+from typing import Any
+
 from easypost.constant import (
     API_BASE,
     API_VERSION,
     INVALID_REQUESTS_VERSION_ERROR,
     SUPPORT_EMAIL,
     TIMEOUT,
 )
+from easypost.easypost_object import convert_to_easypost_object
 from easypost.hooks import RequestHook, ResponseHook
+from easypost.requestor import RequestMethod, Requestor
 from easypost.services import (
     AddressService,
     ApiKeyService,
@@ -138,3 +142,14 @@ def subscribe_to_response_hook(self, function):
     def unsubscribe_from_response_hook(self, function):
         """Unsubscribe functions from running when a response occurs."""
         self._response_hook -= function
+
+    def make_api_call(self, method: RequestMethod, endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Make an API call to the EasyPost API.
+
+        This public, generic interface is useful for making arbitrary API calls to the EasyPost API that
+        are not yet supported by the client library's services. When possible, the service for your use case
+        should be used instead as it provides a more convenient and higher-level interface depending on the endpoint.
+        """
+        response = Requestor(self).request(method=method, url=endpoint, params=params)
+
+        return convert_to_easypost_object(response=response)

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "easypost"
 description = "EasyPost Shipping API Client Library for Python"
-version = "10.5.1"
+version = "10.6.0"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

tests/cassettes/test_client_make_api_call.yaml

@@ -6,9 +6,10 @@
 
 from easypost.easypost_client import EasyPostClient
 from easypost.errors import TimeoutError
+from easypost.requestor import RequestMethod
 
 
-def test_api_key():
+def test_easypost_client_api_key():
     """Tests setting and getting API keys from different client objects."""
     client1 = EasyPostClient(api_key="123")
     assert client1.api_key == "123"
@@ -17,23 +18,23 @@ def test_api_key():
     assert client2.api_key == "456"
 
 
-def test_no_api_key():
+def test_easypost_client_no_api_key():
     """Tests that we raise an error when no API key is passed to the client."""
     with pytest.raises(TypeError) as error:
         EasyPostClient()
 
     assert "missing 1 required positional argument: 'api_key'" in str(error.value)
 
 
-def test_invalid_client_property():
+def test_easypost_client_invalid_client_property():
     """Tests that we throw an error when attempting to use an invalid property of a client."""
     with pytest.raises(AttributeError) as error:
         EasyPostClient("123").invalid_property()
 
     assert str(error.value) == "'EasyPostClient' object has no attribute 'invalid_property'"
 
 
-def test_api_base():
+def test_easypost_client_api_base():
     """Tests that we can override the API base of the client object."""
     client1 = EasyPostClient(api_key="123")
     assert client1.api_base == "https://api.easypost.com/v2"
@@ -43,7 +44,7 @@ def test_api_base():
 
 
 @patch("requests.Session")
-def test_client_timeout(mock_session, basic_shipment):
+def test_easypost_client_timeout(mock_session, basic_shipment):
     """Tests that the timeout gets used properly in requests when set."""
     mock_session().request.side_effect = requests.exceptions.Timeout()
     client = EasyPostClient(api_key=os.getenv("EASYPOST_TEST_API_KEY"), timeout=0.1)
@@ -53,3 +54,14 @@ def test_client_timeout(mock_session, basic_shipment):
         assert False
     except TimeoutError as error:
         assert error.message == "Request timed out."
+
+
+@pytest.mark.vcr()
+def test_client_make_api_call():
+    """Tests that we can make an API call using the generic make_api_call method."""
+    client = EasyPostClient(api_key=os.getenv("EASYPOST_TEST_API_KEY"))
+
+    response = client.make_api_call(method=RequestMethod.GET, endpoint="/addresses", params={"page_size": 1})
+
+    assert len(response["addresses"]) == 1
+    assert response["addresses"][0]["object"] == "Address"