Major API versions should be distinguishable at the API's external URI rather than being encoded independently into every resource operation or into internal Mule flow names. MuleSoft recommends including the consumer-facing API version in the application URL, for example /v1/..., so clients can explicitly select the major API contract they intend to consume.
RAML supports this cleanly through the baseUri. A version variable can be included in the base URI, for example baseUri: https://api.example.com/v{version}, with the corresponding version or base URI parameter defined in the specification. This keeps the versioning concern at the API contract and endpoint-addressing level.
Changing every operation would unnecessarily duplicate version information. Modifying generated APIkit flow names affects Mule implementation internals but does not provide distinct public API addresses. Similarly, manually changing generated HTTP listeners after scaffolding makes the implementation diverge from the API specification and weakens API-led lifecycle management.
MuleSoft's versioning guidance explicitly recommends exposing the major version in the API URL and using simple major identifiers such as v1, v2, and so forth.
Reference topics: API Versioning; RAML baseUri; Base URI Parameters; Major API Versions.
Official documentation: https://docs.mulesoft.com/exchange/to-change-raml-version
===============================================================
