Skip to main content

API Versioning

Ensuring backward compatibility and smooth transitions.

Overview​

As your application evolves, your APIs will inevitably change. API versioning allows you to introduce breaking changes without breaking existing clients (like older versions of your frontend or third-party integrations).

Versioning Strategy​

LibreApps Desktop uses URL versioning. The version number is included as a prefix in the API path:

  • GET /api/v1/users: The current stable version of the users API.
  • GET /api/v2/users: A newer version with breaking changes.

When to Version​

You should introduce a new API version when you make a breaking change, such as:

  • Removing a field from a response.
  • Changing the data type of a field.
  • Renaming an endpoint.
  • Changing the required parameters for a request.

Non-breaking changes (like adding a new field to a response or creating a new endpoint) do not require a new version.

Implementation in Spring Boot​

You can handle versioning in your Spring Boot controllers using the @RequestMapping annotation:

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    // ...
}

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    // ...
}

Deprecation Policy​

When a new API version is released, the older version should be marked as deprecated. Provide a clear timeline for when the deprecated version will be retired, giving clients enough time to migrate to the new version.

Best Practices​

  • ✅ Do this: Use a simple, incrementing integer for your version numbers (v1, v2, v3).
  • ✅ Do this: Document the changes in each new API version in your changelog.
  • ❌ Don't do this: Support too many old API versions simultaneously; it increases maintenance overhead and complexity.