ForhoppPay Connect — API Versioning

Feature Reference: FR-30 | Components: ApiVersionFilter, ApiVersionHolder, ApiVersionResponseAdvice

---

1. Overview

ForhoppPay Connect supports API versioning via the ForhoppPay-Version header. This allows backward-compatible evolution of the API while giving merchants control over which version they use. If no version is specified, the latest stable version is used.

---

2. Version Header

ForhoppPay-Version: 2024-01-01

Format: YYYY-MM-DD (date of the API version release).

---

3. Version Lifecycle

Phase	Duration	Behavior
Current	Ongoing	Default version for new integrations
Supported	12 months after deprecation	Fully functional, deprecation warnings
Deprecated	After 12 months	May return errors, migration required

Breaking changes are only introduced in new versions. Non-breaking additions (new fields, new endpoints) are added to all versions.

---

4. Implementation

4.1 ApiVersionFilter

Runs in the filter chain before controllers:

1. Extract ForhoppPay-Version header from request
2. Parse and validate version string
3. Store in ApiVersionHolder (ThreadLocal)
4. Continue filter chain
5. Clear ThreadLocal in finally block

4.2 ApiVersionHolder

Thread-local storage for the current request's API version:

public class ApiVersionHolder {
    private static final ThreadLocal<String> VERSION = new ThreadLocal<>();

    public static void set(String version) { VERSION.set(version); }
    public static String get() { return VERSION.get(); }
    public static void clear() { VERSION.remove(); }
}

4.3 ApiVersionResponseAdvice

A ResponseBodyAdvice that adds the version header to all responses:

@ControllerAdvice
public class ApiVersionResponseAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public Object beforeBodyWrite(Object body, ..., ServerHttpResponse response) {
        String version = ApiVersionHolder.get();
        if (version != null) {
            response.getHeaders().add("ForhoppPay-Version", version);
        }
        return body;
    }
}

---

5. Version Behavior

Scenario	Behavior
No header provided	Use latest stable version
Valid version header	Use specified version
Invalid version format	Use latest stable version (log warning)
Unknown version date	Use latest stable version (log warning)

---

6. Response Headers

Every API response includes:

ForhoppPay-Version: 2024-01-01

This confirms which version was used to format the response.

---

7. Correctness Properties

#	Property	Validates
40	Response formatted per version header; default to latest if not provided	FR-30.1, FR-30.2

---

8. Changelog Convention

Each version release includes a changelog documenting:

• New endpoints
• New request/response fields
• Changed behaviors
• Deprecated features
• Migration guides

Published at https://docs.forhopp.com/changelog.

---

Last Updated: March 2026