3

I always see the discussion when there's an API version in the URL where to point the versionless one.

I mean look at these three URLs.

http://host/api/customers/1
http://host/v1/api/customers/1
http://host/v2/api/customers/1

In every blog post I read, they are talking about where to point the first URL. I would first of all disable that URL, what good can come out of it? And even if I have that URL I would obviously point that to the oldest supported version, and hopefully retire it with that! (Because only reason me having that URL would be that before publishing I would've forgotten there could be versions)

It's not just that I can't see the point in binding it to the newest API but it's like the worst thing to do, even stupid!

What are your thoughts on this? Why do even people write about that pardon me stupid URL?

5

Some people use the first URL format for the first version of their API, because they did not think about how to manage versioning at that point (or delayed that decision till they need a second version). Others use it because they do not use the URL to determine the version to use, or allow for alternative ways to tell the server which version is in use (headers, etc.).

Ultimately, the most important thing when publishing an API is to make sure it is consistent, logical and well-documented.

I agree with you that, when you provide URLs in which the version identifier of the API is visible, having a versionless URL has little to no value (except if it is how version 1 of the API is to be used), and can be confusing to API consumers. It'd be nice if you could link to a few of the blog posts you've read that advocate its use, because I personally haven't come across them.

If the first URL is to be provided, with a proper version detection mechanism in place (use of a dedicated header like X-API-Version or use of a dedicated MIME type), then it's the other two URLs that are probably better not to exist.

(It should be noted that using X-API-Version does not solve but just moves the problem around; because if that header is not set, how should your API behave? Whether it should behave as v1, or return an error with a message telling the API consumer to provide the version, the same can probably be said of the first URL format.)

Interesting article on the topic : You API versioning is wrong, which is why I decided to do it 3 different wrong ways (Troy Hunt)

1
  • I read that post by Troy Hunt as well and had a laugh, I will try to improve my question with references :)
    – EralpB
    Jan 11 '17 at 19:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.