Mark preferred version of API

[IvanGoncharov]

Some APIs have multiple swagger files documenting different versions.
In my service, by default show preferred version of API.
Could you please mark preferred version somehow?
For example, Git support symlinks, so you can make $api/preferred/ point to dir with preferred version.

[devigned]

Hmm... I guess we could do this, but I'm not sure we should think about versions this way. All versions that are not preview should be equally good for customers to consume. There is no preference other than feature set.

We could provide guidance to point toward the latest, or simply have the convention rather than having to keep updating the symlink when a new version is available.

[IvanGoncharov]

@devigned

All versions that are not preview should be equally good for customers to consume.

Yes, but imagine person see your API for the first time without any previous experience with it.
I think, to explain it litter bit better I need to provide some background.

I working on catalog of OpenAPI specs for public APIs.
Some 3rd-party tools/services access it through my own API.
Have sample site to show simplest possible UI, I think this screenshot illustrate my current strategy:

So user always presented with the latest version but it still possible to choose previous ones.

We could provide guidance to point toward the latest, or simply have the convention rather than having to keep updating the symlink when a new version is available.

Alternative you can mark it inside spec itself.
In my catalog I currently use x-preferred with boolean as the value.
I borrow this semantic from Google Discovery, see this

[salameer]

Hi @IvanGoncharov

The API documented inside the Stable folder version are the ones that customer would write stable code on, "Preffered" would be a bit subjective depending on what the customers are looking for. Some prefer latest stable other prefer to lock on a specific version.

Ofcourse the more recent version that you adopt the more goodness of features you get :)

Thanks

Closing and please re-open if you have other questions

Thanks

Samer