Production incident19 Jun 20262 min read

Production Breakage After RestCountries API Deprecation (v5 Migration and Caching Fix)

The application relies on the RestCountries API to populate country, state, and phone-related fields across multiple forms. This data feeds location-dependent workflows and validation logic in the frontend.

#API#SoftwareEngineering#WebDevelopment#Debugging#Production

0 likes · 1 views

Architecture showing RestCountries API v3 to v5 migration. Before: Frontend → deprecated API (no auth). After: Frontend → Backend → Redis + v5 (API key protected). — Architecture change: Moved from direct frontend API calls to backend-proxied requests with Redis caching for performance and API key protection.

Investigation

The first signal was a failed request to the RestCountries API. Instead of returning data, the request triggered a CORS error in the browser.

To isolate the issue, the API endpoint was tested directly in the browser. The response returned:

text

{
  "success": false,
  "data": null,
  "errors": [
    {
      "message": "This API version has been deprecated..."
    }
  ]
}

This confirmed the issue was not frontend-related. The API itself had changed.

Reviewing the RestCountries documentation showed that:

The legacy API had been deprecated.
Version 5 introduced a new response format.
Access now requires registration and an API key.

This explained both the CORS issue and the missing data in production.

Root Cause

The application depended on a deprecated version of the RestCountries API. Once the legacy endpoints were disabled, all country-related requests failed.

Additionally:

The new API requires an API key, which cannot be exposed on the frontend.
The response structure changed, breaking existing parsing logic.

Fix / Resolution

The integration was reworked with the following changes:

Migrated all country-related API calls to RestCountries v5.
Moved requests from the frontend to the backend to protect the API key.
Introduced Redis caching to store country data and reduce repeated external calls.
Updated frontend logic to match the new response structure.
Ensured all dependent fields (country, state, phone) correctly consume the updated data.

After deployment, all location-related fields resumed normal behavior.

Takeaways

External APIs are not stable dependencies. Even widely used services can introduce breaking changes without direct notification.
A working integration today does not guarantee future reliability without monitoring or version awareness.
Always proxy third-party APIs that require authentication through the backend.
Cache static or rarely changing data like country lists to reduce latency and dependency on external services.
When debugging production issues, test API endpoints outside the application to quickly separate frontend, backend, and third-party failures.
Periodically audit external API usage to catch deprecations before they cause runtime failures.

Oodo Roland

Fullstack engineer. I build and deploy production systems and write about what breaks along the way.

Found this useful? Pass it on.