Why check Apache Fineract API breaking changes before an upgrade
Check Fineract's REST API for breaking changes before you upgrade, because an upgrade can alter request or response contracts that your integrations, generated clients and front end depend on, and those failures often appear only in production traffic. Your core banking backend is rarely used alone. Payment switches, reporting jobs, onboarding portals and the Mifos web app all call the same endpoints, and a renamed field or changed parameter can break one of them without any error in the Fineract logs. The compatibility check is the earliest signal you have that the contract has moved, so it belongs in the upgrade plan before the database migration is scheduled.
The supported path is to move onto the current stable release, 1.15.0, from a release line the project still maintains. The Fineract README states that official releases are created quarterly, at the end of each quarter, under the ASF release policy, and that end-of-life releases are archived. That cadence means your upgrade calendar will recur, so a repeatable compatibility check is more useful than a one-off review. Confirm your current version against the Apache Fineract platform documentation and the release notes for every version between yours and the target before you decide how many steps the move requires.
Treat the compatibility check as one input to the upgrade, not a substitute for testing. It compares the specification against a baseline under breaking change rules, but it cannot see how your own clients use an endpoint, what your custom code expects from a response, or whether a database migration changes behavior that the specification does not describe. Pair it with regression tests of your integrations, generated client builds, and staff workflows in a non-production environment that runs the same Liquibase migrations you will run in production. Ask your team to record each reported change and its owner before go-live.
Which Fineract changes affect integrations
This table maps release facts from the 1.14 to 1.15 window to the effect each one can have on systems that call Fineract. Read each row as a question to answer before upgrading: what changed, who calls the API, and what you must confirm or test. Items the supplied material does not detail are marked for confirmation in the 1.15.0 release notes rather than assumed.
| Change | Impact on API consumers | Action needed |
|---|---|---|
| 1.15.0 is the current stable release | Clients pinned to 1.14 face a moving target, and the 1.15.0 line is the baseline to compare against | Pin the target version, then confirm in the 1.15.0 release notes which endpoints or response fields changed |
| 1.14 to 1.15 SQL injection fixes | Request handling for affected inputs may change, so integrations that send unusual or unvalidated values could see different responses | Replay your integration test suite with edge-case inputs and confirm the fixed endpoints in the release notes |
| Liquibase runs only on write instances | Callers hitting read or batch instances will not trigger schema changes, but a read instance can serve stale or mismatched data until the schema is migrated | Confirm the instance roles in your deployment and sequence the migration before routing traffic |
| Liquibase-only Spring profile on Kubernetes | A separate migration job can finish before app instances roll out, so integrations see the new schema only after the job succeeds | Verify job completion in your pipeline and check that no client depends on schema state during the rollout |
| Tenant header requirement | Every request must carry the Fineract-Platform-TenantId header, so clients that omit or mis-set it will fail after gateway or proxy changes | Audit all clients and gateway rules for the header and test each tenant explicitly |
| Mifos web app version pairing | A front end built for another backend release can call endpoints or fields that no longer match | Match the Mifos web app version to the Fineract release and run staff workflow tests after the upgrade |
| Authentication defaults | The documented development login must be changed for real deployments, so clients using defaults may break after hardening | Confirm your OAuth2 or basic authentication settings and rotate credentials used by integrations |
Running the check and acting on the report
This sequence turns the compatibility check into a decision: each breaking change is traced to the integrations that depend on it, then fixed, versioned or deferred. The upgrade proceeds only when the report is clean and client tests pass against the target build.
Record the currently deployed specification
Capture the OpenAPI specification served by the Fineract release you run today, and store it in version control with the release tag and the date it was taken. The owner is the platform engineer responsible for the deployment. Done means the file is committed, its source build is identified, and someone other than the author can confirm which release it describes. This file is the reference point for every later comparison, so an unlabeled copy is not acceptable.
Generate the baseline from develop
Run the project's backward compatibility check so it builds the baseline OpenAPI specification from the develop branch of the Fineract source. Keep the generated file separate from the deployed copy so the two are never mixed up. Done means the baseline is generated from a recorded commit, and the commit hash is written next to the file. If the baseline cannot be generated, stop here and resolve the build problem before comparing anything.
Compare the target release against the baseline
Build the target Fineract version, export its specification, and run the comparison against the baseline under the project's breaking change rules. Keep the target build as a separate artifact, not deployed to any shared environment. Done means the tool has produced a report for the target version and the report names the spec versions it compared.
Triage each finding against your consumers
For every breaking change, list the endpoints, request fields and response fields affected, then find which of your integrations, generated clients, scripts and front ends call them. Involve the owners of each consumer, since only they know which fields they read and how they handle nulls or new enum values. Done means each finding is tagged with its affected consumers and an owner, and no finding is left without a decision in the triage log.
Decide to adapt, version or defer each change
For each affected finding, choose one path: update the consumer to the new contract, keep a compatibility layer such as a gateway transformation or a versioned client, or defer the upgrade until the consumer is ready. Record the decision, the reason and the owner in the same log. Done means every affected finding has a recorded decision, and any deferral names the blocking consumer so the upgrade plan can be reconsidered.
Rerun the check after fixes
After consumer changes or compatibility layers are in place, rerun the comparison against the same baseline and the same target build. Compare the new report with the previous one to confirm that resolved findings are gone and that no new ones appeared. Done means the rerun is recorded with its date and commit references, and any remaining findings have a documented decision.
Set the rollback point before any migration
Before the target build is deployed to any environment that runs Liquibase, confirm that the team can revert to the previous build and its database backup. Liquibase migrations run only on write instances, so the rollback point is the moment before the first write instance starts with the new build. Done means the rollback steps are written, a tested backup of the database exists, and the team agrees that the target build can be discarded at this point without data changes.
Gate the upgrade on a clean report and client tests
Allow the upgrade only when the final report has no unresolved breaking changes, and when generated clients and front ends pass their test suites against the target build in a non-production environment. Confirm the Mifos web app version matches the target release before testing. Done means the gate checklist is signed by the platform owner and the consumer owners, and the test results are attached to the change record.
Preparing your integration inventory and test environment
A breaking change report only protects you if you know who depends on the API and can prove the upgraded system behaves as before. These four cards cover the inventory, the baseline specification, the test tenant and the recovery point that together make the comparison actionable.
Inventory every REST API consumer
List each caller of the Fineract REST API: custom services, generated clients, the Mifos web app, reporting jobs, payment switches and notification integrations. For each one, record the endpoints it calls, the API version it was built against and the tenant it uses. Breaking change rules flag endpoints in the specification, but only this list tells you which flagged change actually hurts your operations. Confirm that batch and scheduled callers are included, since they often run outside normal business hours.
Capture the current specification
Save a copy of the OpenAPI specification your integrations are running against today, under version control and tagged with the Fineract release it came from. The comparison in the documentation generates its own baseline from the develop branch, so your copy is the record of what your consumers depend on. Store it alongside the generated client code that was built from it, so you can rebuild either one if a diff is disputed later.
Build a non-production tenant
Create a test tenant with configuration that resembles production: the products, offices, charge rules, accounting setup and roles your consumers use. Load representative data, including accounts in several lifecycle states, so that read and write calls exercise real paths. Do not reuse the default development login in any shared environment. Replace it with named accounts and secrets managed by your identity and secrets tooling before any tester or pipeline connects.
Back up the tenants database and schemas
Take a verified backup of the tenants database and of each tenant schema before any test or upgrade step touches them. Confirm that you can restore to a separate environment and that the restored tenant answers API calls. Ask your database team to confirm the backup method, retention period and restore time, since these determine how far back a failed upgrade can roll you. Treat the backup as the rollback point for the whole integration test cycle.
Assign an owner to each consumer
Name one accountable owner for every consumer on the inventory, with a backup contact. The owner decides whether a flagged change is acceptable, schedules the fix and runs the regression test for that integration. Without named owners, breaking change reports tend to be read by no one, and generated clients or front ends are updated late or not at all. Record ownership in the same inventory so it is reviewed each time a release is planned.
Testing generated clients and front ends
Clients generated from the Fineract OpenAPI specification are the first consumer to check, because the generator turns any schema change into code changes. Regenerate each client from the candidate specification in a branch, not from the old one, and review the diff of generated models, method signatures and enum values before anything else. Removed or renamed fields usually break at compile time, but a changed type or a new required field can compile cleanly and fail only when a request is sent.
- Regenerate from the candidate spec: Keep the generator version and configuration pinned so that diffs reflect Fineract changes, not tooling changes.
- Run contract tests against a candidate instance: Call each endpoint your code uses for create, read, update and the status transitions it depends on, and assert on response shape and values.
- Cover error paths: Confirm how your client handles validation errors and authorization failures from the new version, since error payloads are a common source of breakage.
- Check enum and date handling: Test any code that parses status values or date fields against the new release's responses.
- Pin the client version per environment: Make sure staging and production run the same generated client build that passed testing.
Before cutover, confirm that every generated client you ship has a passing contract run recorded against the upgraded instance.
The Mifos web application is the front end the Fineract README uses in its Kubernetes example, and it is a separate artifact with its own release line. Match its version to the Fineract release you are moving to, then test it against the upgraded backend rather than assuming the previous web build still works. Staff workflows are where mismatches surface, because they touch many endpoints in sequence. Check the front-end release notes and environment variables against your deployment before the test cycle starts.
- Pair versions deliberately: Confirm which web app release matches the target Fineract version and record the pairing in your change plan.
- Exercise core staff workflows: Walk through client onboarding, loan application, approval, disbursement, repayment, savings deposit and withdrawal, and end of day views.
- Check configuration and branding settings: Review environment variables and any custom UI changes against the new build.
- Test with real permission sets: Log in with each staff role your organization uses, since menu and action visibility depends on permissions.
- Verify reports and exports: Run the reports staff depend on and compare totals against the pre-upgrade environment.
Record the web app build, the Fineract version and the tested role list together so that an auditor or support engineer can reproduce the test.
Custom front ends and batch integrations, such as nightly file loads, reconciliation jobs and reporting extracts, often call Fineract in ways the core team never tests. Inventory every caller, including scheduled jobs and third-party systems that use service accounts, and treat each as its own test target. Batch jobs deserve particular attention because a failure may not appear until the next business cycle, and Fineract's batch endpoints and end-of-day processing can behave differently under load.
- Inventory all callers: List each application, script and scheduled job that calls Fineract, with its owner and the endpoints it uses.
- Replay representative batches: Run recorded or synthetic batch requests against a candidate instance and compare results with the current version.
- Test idempotency and retries: Confirm that retry logic still produces the intended outcome when a request is repeated.
- Check pagination and filters: Verify that list endpoints return the same records and ordering your code expects.
- Confirm scheduling dependencies: Make sure jobs that depend on end-of-day completion run after the upgraded batch process finishes.
Before sign-off, confirm that every caller in the inventory has a documented test result and an owner who accepted it.
Every consumer depends on two things that a specification diff rarely reveals: how the tenant is identified and how the caller is authenticated. Fineract is multi-tenant, and API requests carry a Fineract-Platform-TenantId header, so a client that sends the wrong tenant identifier may still reach a valid endpoint while reading or writing the wrong data. Authentication is configured through OAuth2 or HTTP basic authentication, and the documented development login must be replaced in any real deployment. Test these paths on the upgraded instance itself, with the same identity configuration production uses.
- Send the tenant header explicitly: Confirm that each consumer sends Fineract-Platform-TenantId and that the response reflects the intended tenant's data.
- Test a wrong tenant: Verify that a request with an unknown or incorrect tenant identifier fails as expected.
- Validate token flows: For OAuth2 consumers, check token issuance, expiry, refresh and scopes against the upgraded instance.
- Confirm service accounts: Test batch and integration credentials, and confirm that the default development login is disabled.
- Check HTTPS settings: Confirm that clients connect over TLS using the configured SSL settings.
A specification diff can show that the authentication schema is unchanged, but only a live call proves that the caller's tenant and credentials still resolve as intended.
What makes API compatibility work take longer
This table lists the factors that make a Fineract API compatibility review larger or smaller, along with what to inventory before you ask for a quote. Use it to see which rows apply to your estate, since cost and duration depend on the written scope and the size of your integration inventory.
| Driver | Why it changes effort | How to keep it manageable |
|---|---|---|
| Integrations and generated clients | Each consuming system, and each client generated from the OpenAPI spec, needs its own review and regression run after the baseline comparison. | Keep a current list of consumers, owners and the spec version each one was generated from. |
| Custom endpoints or extensions | Custom code that exposes or depends on non-standard paths or fields must be checked by hand, since the report only covers the published specification. | Document every custom path and field, and confirm which ones are visible to the compatibility check. |
| Breaking findings in the report | A longer breaking change report means more decisions about whether to adapt callers, pin old behavior or accept the change. | Triage findings by consumer impact before scheduling client regeneration or code changes. |
| Mifos web app customizations | Custom screens or scripts that call changed endpoints must be retested against the matching front end version. | Record which screens and calls were customized and tie each to a test case. |
| Batch and event consumers | Batch request payloads and external business events such as ClientCreated, if enabled, can change shape without appearing as a simple endpoint change. | List every batch job and event subscriber, and confirm whether event publishing is enabled in your environment. |
| Test coverage | Thin automated tests mean more manual checks of products, accounting and integration flows after each change. | Ask what automated coverage exists for the API calls your integrations use before estimating test effort. |
| Tenants sharing one deployment | Each tenant may use different products, settings or integrations, so checks may need repeating per tenant. | Identify which tenants use which endpoints and sample representative tenants first. |
Questions teams ask before checking Fineract API changes
Does the backward compatibility check replace regression testing?
No. The check compares the current OpenAPI specification against a baseline generated from develop and reports changes that break defined compatibility rules. It tells you where the contract moved, not whether your products, accounting setup, end-of-day processing or integrations still behave correctly. A spec can stay compatible while a business rule, default value or batch job changes its result. Treat the report as the first filter for integration work, then run functional regression tests on the loan, savings, accounting and COB flows your organization depends on, and test every integration against a staging copy of your production data before cutover.
What does the check cost in effort, and what drives that effort?
The check itself is a repeatable comparison, so most of the effort sits in reviewing the report and acting on it. Effort rises with the number of endpoints your integrations use, the number of custom modules or extensions that call the API, how many generated clients you maintain, and how many front ends or middleware flows depend on response shapes. Costs have three parts: internal engineer time to run and read the report, the work to fix or adapt each affected consumer, and retesting. Ask any partner for a quote that lists each consumer, each client generation step and each test environment separately.
How long does an API compatibility review take?
The comparison runs as an automated step and usually completes quickly, but the review and remediation take longer and depend on the size of the report. A short report that touches only optional fields is a different job from one that renames or removes endpoints used by several systems. Timelines depend on how many consumers you have, whether generated clients need regeneration, how mature your test automation is, and how much staging capacity you can access. No duration is set by the project, so ask for a timeline built from your own consumer inventory rather than a generic estimate.
What must our team provide before the check starts?
Start with a complete list of every system that calls the Fineract REST API, including mobile apps, reporting jobs, ERP feeds, payment switches, the Mifos web app and custom scripts. For each one, record the Fineract version it targets, the generated client it uses, the endpoints and fields it reads and writes, and the owner who can approve changes. You also need access to a non-production environment with a recent copy of tenant data, a way to build the current and target specifications, and named testers for staff workflows. Without this inventory, the report cannot be mapped to business impact.
Can our in-house engineers run the check themselves?
Yes, if the team has someone who can read OpenAPI specifications, build the project from source or its published artifacts, and interpret compatibility output in terms of client code. The skill that is hardest to build in-house is judging business impact: knowing which changed field affects interest calculation, a posting rule or a regulatory report. Teams with stable integrations and an existing test suite often handle the check internally. Teams that lack Java build experience, a staging environment or a clear owner for each integration usually add a partner for the first cycle and then take the process over.
What should we do when the report lists breaking changes?
Do not upgrade production until each breaking change has an owner and a decision. For each entry, identify the affected consumers from your inventory, decide whether to adapt the consumer, pin the old behavior or defer the upgrade, and document the choice. Regenerate affected clients from the new specification, update request and response handling, and rerun the functional tests for those flows. Keep the baseline report with the change record so auditors and internal reviewers can see what changed and how it was tested. If a breaking change touches a core product or accounting flow, schedule extra business sign-off before the release window.
How often should we rerun the check across quarterly releases?
Fineract publishes official releases quarterly, at the end of each quarter, so run the check whenever you plan to move to a new release and again when you assess a later one. Running it only at upgrade time leaves little room to plan consumer changes, so many teams also run it against the release they are about to adopt during the quarter before it ships. Rerun it after any custom code change that touches the API layer, since your own extensions can introduce differences that the upstream report does not explain. Keep one current baseline per release line you support.
How DeployOpen scopes and delivers an API upgrade check
DeployOpen treats the API compatibility check as one part of a wider upgrade plan for your Fineract deployment. We scope the baseline, run the comparison against your own integrations and front ends, and hand over a documented result your team can repeat for future releases. The work runs inside infrastructure you control.
How we scope
- The written scope names the Fineract versions, the develop baseline and the current specification to compare.
- It lists which integrations, generated clients and front ends must be tested against the report.
- Deliverables, exclusions and acceptance criteria are agreed in writing before any work starts.
- Engagements are fixed-scope, so the quote follows directly from that agreed written scope.
How we build
- We generate the baseline OpenAPI specification from develop and run the compatibility check in your environment.
- We review each flagged breaking change against the endpoints your integrations actually call.
- We regenerate affected clients and run them against a test instance of the target release.
- We record each change, its owner and the code or configuration that needs to move.
How we hand over
- You receive the breaking change report with an annotated list of findings and their impact on your integrations.
- Runbook steps explain how to rerun the check, read the report and update the baseline for later releases.
- Test results for generated clients and front ends are documented with the versions tested.
- Knowledge transfer sessions cover the decisions made and the open items your team must confirm.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
- A retainer can cover rerunning the compatibility check when a new Fineract release is planned.
- Support scope, response expectations and renewal terms are confirmed in writing before they apply.
- Your team keeps ownership of production changes, with our input on the test evidence behind them.
