Hands-On RESTful API Design Patterns and Best Practices

Versioning

Many books and articles recommend avoiding versioning APIs if possible. However, it's not practical to believe that we'll develop one API that caters to almost every requirement within the first release and never changes, so we avoid versioning altogether. A few others recommend providing different URIs for different (major) version changes. Ideally, we'd manage APIs just like website URLs (most of the time the URL address never changes, regardless of any changes/implementations).

The general rules of thumb we'd like to follow when versioning APIs are as follows:

• Upgrade the API to a new major version when the new implementation breaks the existing customer implementations
• Upgrade the API to a new minor version of the API when ...