### Problem to solve From the feedback we've long received about the API docs ([recent example](https://docs.gitlab.com/ee/api/api_resources.html), GitLab-internal), users are confused about `gitlab.example.com` in our example URLs: - Self-managed users don't always realize they need to use their instance's URL. - SaaS users don't always realize they need to use `gitlab.com`. ### Further details This URL is decided in [style guide](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#fake-urls) and [API topic template](https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#api-topic-template). ### Proposal Possible approaches. Modify the API doc template to: - Include a note above each example that uses the example URL. The note would say that you should use your instance URL, so for example SaaS users should use `gitlab.com`. - Start each page with an explanation of the example URL (like above). - Explain the example URL (like above) for REST API (and how to build the base URL: add /api/v4/ for the current) either in https://docs.gitlab.com/ee/api/ or https://docs.gitlab.com/ee/api/api_resources.html, and then link to it, either from the top of each API page, or from near each example request. I don't think this is the best approach, but this is the only one I can think of at the moment. ### Who can address the issue TW team, @sselhorn as the style guide DRI ### Other links/references <!-- E.g. related GitLab issues/MRs -->