Networking Layer and HTTP Abstraction
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/core/net/IHttpClient.java
- src/main/java/com/resend/core/net/impl/HttpClient.java
- src/main/java/com/resend/core/service/BaseService.java
- src/main/java/com/resend/core/net/RequestOptions.java
- src/main/java/com/resend/Resend.java
- src/main/java/com/resend/core/net/HttpMethod.java
- src/main/java/com/resend/core/net/AbstractHttpResponse.java
The Networking Layer provides a structured abstraction for making HTTP requests to the Resend API. It decouples the core service logic from specific HTTP library implementations through an interface-driven design, allowing for flexible configuration of timeouts, proxies, and custom clients.
This layer handles the lifecycle of an API call, including request construction, header management, authentication via API keys, and response deserialization.
Sources: src/main/java/com/resend/core/net/IHttpClient.java, src/main/java/com/resend/core/net/impl/HttpClient.java, src/main/java/com/resend/core/service/BaseService.java
Core Architecture
The architecture follows a provider pattern where the IHttpClient interface defines the contract for networking operations. The HttpClient class provides the default implementation using the OkHttp library.
Class Relationship
The following diagram illustrates the relationship between the entry point, the service layer, and the networking abstraction.
Request Execution Flow
API requests originate in specific service modules (e.g., Emails, Domains) and pass through the BaseService execution logic before reaching the HTTP client implementation.
The HTTP Client Implementation
The default HttpClient manages connection pooling and request execution using OkHttpClient. It targets a specific base URL and attaches necessary metadata to every outgoing call.
Configuration Constants
| Constant | Value | Description |
|---|---|---|
BASE_API | https://api.resend.com | Default target for API requests. |
USER_AGENT | resend-java/[version] | Identifies the SDK version to the server. |
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:26-29
Request Normalization
The client enforces specific URL structures during initialization. It ensures the baseUrl is a valid HTTP/HTTPS URL and removes any trailing slashes to prevent malformed paths when appending endpoints.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:286-302
Header and Options Management
The RequestOptions class allows users to customize individual requests without modifying the global client state.
Key Request Headers
- Authorization: Carries the API Key as a Bearer token.
- Accept: Set to
application/jsonby default. - Idempotency-Key: Optional header provided via
RequestOptionsto prevent duplicate operations. - User-Agent: Used for SDK telemetry.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:159-178, src/main/java/com/resend/core/net/RequestOptions.java:10-25
Multipart Request Support
The networking layer supports multipart/form-data for file uploads, primarily utilized by the contact import feature.
The performMultipart method accepts either a java.io.File or a byte[]. It automatically wraps these in a MultipartBody and adds supplementary fields (like mapping configurations) as JSON strings.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:204-273, src/main/java/com/resend/core/net/IHttpClient.java:62-118
Client Customization and Timeouts
The Resend.Builder provides a fluent API to configure the networking behavior. If you provide specific timeouts or a proxy, the builder creates a new OkHttpClient instance derived from the shared connection pool.
| Configuration Method | Description | Default |
|---|---|---|
connectTimeout(Duration) | Time to establish a connection. | 10 Seconds |
readTimeout(Duration) | Time to wait for data from the server. | 10 Seconds |
writeTimeout(Duration) | Time to wait while sending a request body. | 10 Seconds |
proxy(Proxy) | Routes traffic through an HTTP proxy. | System Settings |
httpClient(IHttpClient) | Replaces the entire networking implementation. | Built-in HttpClient |
Sources: src/main/java/com/resend/Resend.java:260-355
Error Handling and Response Wrappers
The layer uses AbstractHttpResponse<T> to encapsulate HTTP status codes, body content, and success status.
- Status Check: The
BaseServicechecks theisSuccessfulstatus of the response. - Exception Mapping: If a request fails (e.g., 4xx or 5xx status), it throws a
ResendExceptioncontaining the status code and error body. - Deserialization: On success, the
ResendMapperconverts the JSON response string into the requested Java model.
Sources: src/main/java/com/resend/core/service/BaseService.java:147-153, src/main/java/com/resend/core/net/AbstractHttpResponse.java:10-18
Summary
The networking layer provides a robust, interface-based foundation for the Resend SDK. By abstracting the HTTP details into IHttpClient, the SDK maintains a clean separation between business logic and transport protocols, while offering advanced features like idempotency, multipart uploads, and configurable connection parameters.