> While the author doesn't seem to like version based APIs very much, I always recommend baking them in from the very start of your application.

You don’t really need to do that for REST APIs. If clients request application/vnd.foobar then you can always add application/vnd.foo.bar;version=2 later without planning this in advance.

▲

9dev 2 days ago | parent | next [-]

Actually, there’s nothing stopping you from using a custom "Version: 2" Header in requests and responses

▲

946789987649 3 days ago | parent | prev | next [-]

If you use something like an OpenAPI generator and want to have different DTOs in your version 2, then you cannot do what you suggested.

	▲	jamietanna 2 days ago \| parent \| next [-]
		I've been using OpenAPI for years with multiple versioning types (header based, content negotiation + media type based) and haven't had issues across Java, Typescript or Go with generating the right code for it
	▲	JimDabell 3 days ago \| parent \| prev [-]
		You can specify multiple media types in OpenAPI.

▲

lazyasciiart 3 days ago | parent | prev | next [-]

Most REST APIs don’t support that. So you don’t need versioning for APIs that already have a request type specified.

▲

JimDabell 3 days ago | parent [-]

I’m not sure what you mean in the context of a discussion about how to design APIs. If you are the one designing an API, it’s up to you what you support.

	▲	lazyasciiart a day ago \| parent [-]
		We call that baking them in from the very start of your application, which is what you claimed this didn’t need.

▲

spixy 2 days ago | parent | prev [-]

The problem is with parameters (or headers) you are still stuck with same API schema (you cannot rename it, etc).

But thanks to versions, in my job we renamed old APIs like /v1/oauthApple and /v1/oauthGoogle to /v2/login/oauth/apple and /v2/login/oauth/google, looks so much better.

	▲	JimDabell 2 days ago \| parent [-]
		> The problem is with parameters (or headers) you are still stuck with same API schema (you cannot rename it, etc). That doesn’t make sense. The whole point of creating a new version is to change the schema. And what do you mean “rename it”? > But thanks to versions, in my job we renamed old APIs like /v1/oauthApple and /v1/oauthGoogle to /v2/login/oauth/apple and /v2/login/oauth/google, looks so much better. Wait, by schema do you mean URL structure? You’re looking at this backwards. The benefit of using headers is that you can keep the same URL. In a REST API, the URL is the primary key. If Client A holds a copy of /v1/foo/1 and Client B holds a copy of /v2/foo/1 then as far as HTTP and REST are concerned, those are two different resources and the clients cannot interoperate. If Client A holds a copy of /foo/1 in application/vnd.foo;version=1 format and Client B holds a copy of /foo/1 in application/vnd.foo;version=2 format, then those clients have the same resource and can interoperate. But if you want to change your URL structure, you can do that too. There’s nothing stopping you from moving /oauthApple to /oauth/apple, you don’t even need a new version to do that – just change the link.