Service Versioning
Stable URLs, predictable upgrades, no surprise breakage.
Major version in the URL
Every REST endpoint includes the major version directly in the path:
https://api.nameapi.org/rest/v5.3/parser/personnameparserOnce published, a major version's request and response shapes do not change in breaking ways. New optional fields may appear, new endpoints may be added, but existing fields keep their meaning.
Breaking changes always result in a new major version — never a silent change to an existing one.
What counts as breaking, and what doesn't
Breaking — new major
- · Removing or renaming a request or response field
- · Changing the type of an existing field
- · Changing the meaning of an enum value
- · Tightening validation that was previously accepted
- · Removing an endpoint
Non-breaking — same major
- · Adding new optional request fields
- · Adding new response fields
- · Adding new endpoints
- · Adding new enum values (clients should default-handle unknowns)
- · Quality improvements in returned values
Old versions stay alive
When a new major version launches, the previous one continues to run in parallel. Customers move at their own pace — integration timing is your call, not ours.
We announce deprecation timelines in advance and never remove a major version without giving a long, fixed migration window. The current version is v5.x; previous v4.x versions remained available for years after v5 launched.
Long overlap
Old and new majors run in parallel for a multi-year window — no race to upgrade.
Advance notice
Deprecation timelines published well before any endpoint is retired — communicated by e-mail and in release notes.
Migration support
Direct help from the engineering team for customers moving across majors — field mappings, edge-case clarifications, parallel-run validation.
You control the upgrade clock
On-premise deployments ship as versioned releases. Customers receive four updates per year with the latest data and feature improvements — major upgrades happen on a schedule the customer agrees to, not ours.
Old releases keep running until you decide to migrate. The same compatibility rules apply: minor releases never break the API contract.
Planning a version migration?
Happy to walk you through what's changed between versions, where the gotchas are, and how to validate the migration in parallel.