Merge branch 'fe-add-preference-for-full-path-vs-full-url' into 'master'

Add FE preference for full path vs full URL

See merge request gitlab-org/gitlab!23193

doc/development/fe_guide/frontend_faq.md

@@ -78,3 +78,71 @@ follow up issue and attach it to the component implementation epic found within
 
 If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) will add a `disabled` class selector to the submit button when the form is submitted.
 To avoid this behavior, add the class `js-no-auto-disable` to the button.
+
+### 5. Should I use a full URL (i.e. `gon.gitlab_url`) or a full path (i.e. `gon.relative_url_root`) when referencing backend endpoints?
+
+It's preferred to use a **full path** over a **full URL** because the URL will use the hostname configured with
+GitLab which may not match the request. This will cause [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/issues/36810).
+
+Example:
+
+```javascript
+// bad :(
+// If gitlab is configured with hostname `0.0.0.0`
+// This will cause CORS issues if I request from `localhost`
+axios.get(joinPaths(gon.gitlab_url, '-', 'foo'))
+
+// good :)
+axios.get(joinPaths(gon.relative_url_root, '-', 'foo'))
+```
+
+Also, please try not to hardcode paths in the Frontend, but instead receive them from the Backend (see next section).
+When referencing Backend rails paths, avoid using `*_url`, and use `*_path` instead.
+
+Example:
+
+```haml
+-# Bad :(
+#js-foo{ data: { foo_url: some_rails_foo_url } }
+
+-# Good :)
+#js-foo{ data: { foo_path: some_rails_foo_path } }
+```
+
+### 6. How should the Frontend reference Backend paths?
+
+We prefer not to add extra coupling by hardcoding paths. If possible,
+add these paths as data attributes to the DOM element being referenced in the JavaScript.
+
+Example:
+
+```javascript
+// Bad :(
+// Here's a Vuex action that hardcodes a path :(
+export const fetchFoos = ({ state }) => {
+  return axios.get(joinPaths(gon.relative_url_root, '-', 'foo'));
+};
+
+// Good :)
+function initFoo() {
+  const el = document.getElementById('js-foo');
+
+  // Path comes from our root element's data which is used to initialize the store :)
+  const store = createStore({
+    fooPath: el.dataset.fooPath
+  });
+
+  Vue.extend({
+    store,
+    el,
+    render(h) {
+      return h(Component);
+    },
+  });
+}
+
+// Vuex action can now reference the path from it's state :)
+export const fetchFoos = ({ state }) => {
+  return axios.get(state.settings.fooPath);
+};
+```