REST Countries

Docs › Countries API › API versions

This page is the architectural background: why v1–v4 can't be kept stable, what /v5's long-term stable promise means, and how future deprecations will be communicated.

Where each version stands

/v5 Maintained
Long-term stable. Stays live indefinitely, even after future major versions ship.
/v4 Deprecated
Returns a JSON:API spec formatted response, with an errors array.
/v3 Deprecated
Returns a JSON:API spec formatted response, with an errors array.
/v2 Deprecated
Returns a JSON:API spec formatted response, with an errors array.
/v1 Deprecated
Returns a JSON:API spec formatted response, with an errors array.

Why v1–v4 can't be kept stable

The previous 4 versions of REST Countries shipped without three fundamental elements required for the long-term stability of an API. Namely:

  • Authentication. v1–v4 were fully open: no API keys, no headers, no ?api-key=. That meant that the APIs couldn't secure themselves against bots or malicious traffic. It also meant that updates to the API couldn't be effectively communicated to users.
  • API hostname separation. v1–v4 operated against the root restcountries.com domain. That meant that requests couldn't easily be separated to run against more resilient servers.
  • Field limitations. v1–v4 limited responses to at most 10 fields when making broad requests. That meant developers needed to make multiple requests to access all the data they needed.

These have all been resolved with /v5, however it's required us to end support for those API versions.

What's different about v5

/v5 is committed to staying live indefinitely. This is because the three fundamental issues above have been resolved:

  • Authentication. v5 now supports API keys (Authorization: Bearer preferred, with a ?api-key= query-string fallback for browser experiments) which will allow us to update users when there are updates to the API (including new data being added, or new versions forthcoming).
  • API hostname separation. All requests are now served from api.restcountries.com. This means we can better protect the endpoint, and scale it up as needed. We aim for 99.995% uptime, which is only possible with this new hostname.
  • Field limitations. There are no longer any limits on the amount of data you can request for a country.

If you have any questions about these changes, please reach out. We'll respond within 24 hours.

Migrating from v1–v4 to v5

Three steps:

  • Create an account if you don't already have one.
  • Read the Countries API docs. Every endpoint and field is documented, including the aggregates, the response_fields response-shape allowlist, the q full-text search, and the per-property filters that v1–v4 didn't support.
  • Update your client to call /v5 with Authorization: Bearer YOUR_KEY in the request header. The bare Authorization: YOUR_KEY form (no Bearer prefix) is also accepted.

Questions

The FAQ covers the common ones. For anything tied to your specific migration, reach out via support.