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

# Description

Adds a generic API request interface to make arbitrary API requests.

# Testing

- New unit test added for the generic API request interface
- All tests passing

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v8.7.0 (2026-02-25)
+
+- Adds generic `makeApiCall` function
+
 ## v8.6.0 (2026-02-03)
 
 - Adds the following functions usable by child and referral customer users:

README.md

@@ -16,7 +16,7 @@ Add this to your project's POM:
 <dependency>
   <groupId>com.easypost</groupId>
   <artifactId>easypost-api-client</artifactId>
-  <version>8.6.0</version>
+  <version>8.7.0</version>
 </dependency>
 ```
 
@@ -25,7 +25,7 @@ Add this to your project's POM:
 Add this to your project's build file:
 
 ```groovy
-implementation "com.easypost:easypost-api-client:8.6.0"
+implementation "com.easypost:easypost-api-client:8.7.0"
 ```
 
 **NOTE:** [Google Gson](http://code.google.com/p/google-gson/) is required.

VERSION

@@ -1 +1 @@
-8.6.0
+8.7.0

pom.xml

@@ -6,7 +6,7 @@
     <groupId>com.easypost</groupId>
     <artifactId>easypost-api-client</artifactId>
 
-    <version>8.6.0</version>
+    <version>8.7.0</version>
     <packaging>jar</packaging>
 
     <name>com.easypost:easypost-api-client</name>

src/main/java/com/easypost/service/EasyPostClient.java

@@ -1,13 +1,17 @@
 package com.easypost.service;
 
+import java.util.Map;
 import java.util.function.Function;
 
 import com.easypost.Constants;
+import com.easypost.exception.EasyPostException;
 import com.easypost.exception.General.MissingParameterError;
 import com.easypost.hooks.RequestHook;
 import com.easypost.hooks.RequestHookResponses;
 import com.easypost.hooks.ResponseHook;
 import com.easypost.hooks.ResponseHookResponses;
+import com.easypost.http.Requestor;
+import com.easypost.http.Requestor.RequestMethod;
 
 import lombok.Getter;
 
@@ -215,4 +219,23 @@ public String getApiVersion() {
     public String getApiBase() {
         return apiBase;
     }
+
+    /**
+     * 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.
+     *
+     * @param method   The HTTP method to use for the request.
+     * @param endpoint The endpoint to call (e.g., "/addresses").
+     * @param params   The parameters to send with the request.
+     * @return A Map containing the API response.
+     * @throws EasyPostException when the request fails.
+     */
+    @SuppressWarnings("unchecked")
+    public Map<String, Object> makeApiCall(RequestMethod method, String endpoint, Map<String, Object> params)
+            throws EasyPostException {
+        return Requestor.request(method, endpoint, params, Map.class, this);
+    }
 }

src/test/cassettes/client/make_api_call.json

@@ -0,0 +1,47 @@
+package com.easypost;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.http.Requestor.RequestMethod;
+
+public final class EasyPostClientTest {
+    private static TestUtils.VCR vcr;
+
+    /**
+     * Set up the testing environment for this file.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @BeforeAll
+    public static void setup() throws EasyPostException {
+        vcr = new TestUtils.VCR("client", TestUtils.ApiKey.TEST);
+    }
+
+    /**
+     * Test making a generic API call.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testMakeApiCall() throws EasyPostException {
+        vcr.setUpTest("make_api_call");
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("page_size", 1);
+
+        Map<String, Object> response = vcr.client.makeApiCall(RequestMethod.GET, "addresses", params);
+
+        List<?> addresses = (List<?>) response.get("addresses");
+        assertEquals(1, addresses.size());
+        Map<String, Object> firstAddress = (Map<String, Object>) addresses.get(0);
+        assertEquals("Address", firstAddress.get("object"));
+    }
+}