Adding custom code

Fern-generated SDKs are designed to be extended with custom code. Your custom code can add additional functionality to the SDK and live in harmony with the generated code.

This page explains how to configure custom logic using a .fernignore file, create custom SDK methods, and add additional dependencies to your SDK.

Adding custom logic

If you want your SDK to do more than just make basic API calls (like combining multiple calls, processing data, adding utilities), you can use .fernignore to protect your custom code from being overwritten during regeneration.

Simply add your custom files to the SDK repository and list them out in .fernignore. Fern won’t override any files that you add in .fernignore.

To get started adding custom code:

1
package com.example.helper;
2
3
public class Helper {
4
5
public static void myHelper() {
6
    System.out.println("Hello World!");
7
}
8
9
}

1
# Specify files that shouldn't be modified by Fern
2
3
src/main/java/<package>/Helper.java

1
import com.example.helper.Helper;
2
3
public class Main {
4
5
public static void main(String[] args) {
6
    Helper.myHelper();
7
}
8
9
}

Adding custom SDK methods

Fern also allows you to add custom methods to the SDK itself (e.g. client.my_method() ) by inheriting the Fern generated client and then extending it.

1
- name: fernapi/fern-java-sdk
2
    version: "..."
3
    config:
4
      client-class-name: BaseClient

1
package com.example;
2
3
import com.example.client.BaseClient;
4
5
public class MyClient extends BaseClient { // extend the Fern generated client
6
7
  public void myHelper() {
8
    System.out.println("Hello World!");
9
  }
10
11
}

1
+ src/main/java/com/example/MyClient.java

1
client.myHelper();

Adding custom client configuration

The Java SDK generator supports builder extensibility through a template method pattern. By extending the generated builder classes and overriding protected methods, you can customize how your SDK client is configured without modifying generated code.

Common use cases include:

• Dynamic URL construction: Replace placeholders with runtime values (e.g., https://api.${DEV_NAMESPACE}.example.com)
• Custom authentication: Implement complex auth flows beyond basic token authentication
• Request transformation: Add custom headers or modify requests globally

How it works

Generated builders use protected methods that can be overridden:

1
public class BaseApiClientBuilder {
2
    protected ClientOptions buildClientOptions() {
3
        ClientOptions.Builder builder = ClientOptions.builder();
4
        setEnvironment(builder);
5
        setAuthentication(builder);    // Only if API has auth
6
        setCustomHeaders(builder);     // Only if API defines headers
7
        setVariables(builder);         // Only if API has variables
8
        setHttpClient(builder);
9
        setTimeouts(builder);
10
        setRetries(builder);
11
        setAdditional(builder);         
12
        return builder.build();
13
    }
14
}

1
package com.example;
2
3
import com.example.api.BaseClient;
4
import com.example.api.core.ClientOptions;
5
6
public class MyClient extends BaseClient {
7
    public MyClient(ClientOptions clientOptions) {
8
        super(clientOptions);
9
    }
10
11
    public static MyClientBuilder builder() {
12
        return new MyClientBuilder();
13
    }
14
}

1
package com.example;
2
3
import com.example.api.BaseClient.BaseClientBuilder;
4
import com.example.api.core.ClientOptions;
5
import com.example.api.core.Environment;
6
7
public class MyClientBuilder extends BaseClientBuilder {
8
9
    @Override
10
    protected void setEnvironment(ClientOptions.Builder builder) {
11
        String url = this.environment.getUrl();
12
        String expandedUrl = expandEnvironmentVariables(url);
13
        builder.environment(Environment.custom(expandedUrl));
14
    }
15
16
    @Override
17
    protected void setAdditional(ClientOptions.Builder builder) {
18
        builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
19
    }
20
21
    @Override
22
    public MyClient build() {
23
        return new MyClient(buildClientOptions());
24
    }
25
}

1
+ src/main/java/com/example/MyClient.java
2
+ src/main/java/com/example/MyClientBuilder.java

Method reference

Each method serves a specific purpose and is only generated when needed:

Common patterns

1
@Override
2
protected void setEnvironment(ClientOptions.Builder builder) {
3
    String baseUrl = this.environment.getUrl();
4
    String tenantUrl = baseUrl.replace("/api/", "/tenants/" + tenantId + "/");
5
    builder.environment(Environment.custom(tenantUrl));
6
}

1
@Override
2
protected void setAuthentication(ClientOptions.Builder builder) {
3
    builder.addHeader("Authorization", () -> 
4
        "Bearer " + tokenProvider.getAccessToken()
5
    );
6
}

1
@Override
2
protected void setAdditional(ClientOptions.Builder builder) {
3
    // Add request tracking
4
    builder.addHeader("X-Request-ID", () -> UUID.randomUUID().toString());
5
    builder.addHeader("X-Client-Version", "1.0.0");
6
    
7
    // Add feature flags
8
    if (FeatureFlags.isEnabled("new-algorithm")) {
9
        builder.addHeader("X-Feature-Flag", "new-algorithm");
10
    }
11
}

1
@Override
2
protected void setHttpClient(ClientOptions.Builder builder) {
3
    OkHttpClient customClient = new OkHttpClient.Builder()
4
        .connectTimeout(30, TimeUnit.SECONDS)
5
        .readTimeout(60, TimeUnit.SECONDS)
6
        .addInterceptor(new RetryInterceptor())
7
        .connectionPool(new ConnectionPool(50, 5, TimeUnit.MINUTES))
8
        .build();
9
    builder.httpClient(customClient);
10
}

Requirements

• Fern Java SDK version: 2.39.1 or later

Adding custom dependencies

To add packages that your custom code requires, update your generators.yml.

1
- name: fernapi/fern-java-sdk
2
  version: "..."
3
  config:
4
    custom-dependencies:
5
      - org.apache.commons:commons-lang3:3.12.0
6
      - org.slf4j:slf4j-api:2.0.7