I am unsure when to increment patch, minor and major using semantic versioning.
If I introduce a new redirect that is performed when a session (a user) is in a specific state, is this considered a incompatible API change which requires me to increment the major version of my project?
How would you handle this? Thanks in advance.
In the context of an API, I would say that SemVer simply doesn't apply; it's a different type of versioning. A patch version has no meaning to a client. In traditional versioning, a patch would indicate a fix with no visible (e.g. public) changes. To a HTTP client, indicating a version change with no discernable impact is virtually meaningless and just adds more work for them. SemVer is also meant to indicate a range of versions, which typically doesn't make sense for HTTP-based APIs. Finally, an API version should be thought of as a media type, which Fielding himself has indicated is the only acceptable way to version an API. It makes sense as 99% of the time, the difference between versions is payload (e.g. media) that is transmitted over the wire. API authors tend to assume that clients employ Tolerant Readers, but this cannot be guaranteed. They also tend assume that there is some unspoken rule that a minor change somehow means that the payload is backward compatible, but - again - that cannot be guaranteed. Any change in media could be incompatible or misunderstood by clients. It's no different than switching from application/xml to application/json.
Redirects and location changes are not only ok, they are even encouraged when appropriate. That is the very essence of Hypermedia As the Engine of Application State (HATEOAS). Using redirects or any of the Location, Content-Location, and Link (RFC 5988) headers are a good way to achieve that. As long as the location of the resource you are linking to does not change across versions, there should be no reason to increment versions just because you moved where it lives.
There is one caveat, which is if you version by URL segment. Versioning by that method puts the API version in the URL path, which violates the Uniform Interface REST constraint. For example, v1/orders/123 and v2/orders/123 are not two different orders, but are the same orders with different representations (e.g. media types). While humans might infer that the identifier is 123, the identifier according to the REST Uniform Interface constraint is the URL path. This style of versioning is problematic for HATEOAS unless you use symmetrical versioning (e.g. all APIs have the same version). Imagine that a client asks for v1/orders/123 and you redirect them to v2/orders/123 or link to v2/customers/456 (from v1). The client may not know how to deal with this change. This is why this style of versioning is the least RESTful. The client should always ask for the version they want, which can be asked for by media type (best), query string (pragmatic), or header. In the case of a redirect, the query string should include the requested API version in the Location if it was present. The media type and header methods will intrinsically flow when the client makes the request to the new Location.
