debian-mirror-gitlab/doc/development/routing.md

110 lines
3.5 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2019-09-04 21:01:54 +05:30
# Routing
2022-10-11 01:57:18 +05:30
The GitLab backend is written primarily with Rails so it uses
2022-08-27 11:52:29 +05:30
[Rails routing](https://guides.rubyonrails.org/routing.html). Beside Rails best
2019-09-04 21:01:54 +05:30
practices, there are few rules unique to the GitLab application. To
support subgroups, GitLab project and group routes use the wildcard
character to match project and group routes. For example, we might have
a path such as:
2020-04-22 19:07:51 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
/gitlab-com/customer-success/north-america/west/customerA
```
2019-09-04 21:01:54 +05:30
However, paths can be ambiguous. Consider the following example:
2020-04-22 19:07:51 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
/gitlab-com/edit
```
2019-09-04 21:01:54 +05:30
It's ambiguous whether there is a subgroup named `edit` or whether
this is a special endpoint to edit the `gitlab-com` group.
To eliminate the ambiguity and to make the backend easier to maintain,
we introduced the `/-/` scope. The purpose of it is to separate group or
project paths from the rest of the routes. Also it helps to reduce the
number of [reserved names](../user/reserved_names.md).
2022-07-16 23:28:13 +05:30
## View all available routes
You can view and find routes from the console by running:
```shell
rails routes | grep crm
```
You can also view routes in your browser by going to [http://gdk.test:3000/rails/info/routes](http://gdk.test:3000/rails/info/routes).
2019-09-04 21:01:54 +05:30
## Global routes
We have a number of global routes. For example:
2020-04-22 19:07:51 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
/-/health
/-/metrics
```
2019-09-04 21:01:54 +05:30
## Group routes
Every group route must be under the `/-/` scope.
Examples:
2020-04-22 19:07:51 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
gitlab-org/-/edit
gitlab-org/-/activity
gitlab-org/-/security/dashboard
gitlab-org/serverless/-/activity
```
2019-09-04 21:01:54 +05:30
To achieve that, use the `scope '-'` method.
## Project routes
Every project route must be under the `/-/` scope, except cases where a Git
client or other software requires something different.
Examples:
2020-04-22 19:07:51 +05:30
```plaintext
2019-12-21 20:55:43 +05:30
gitlab-org/gitlab/-/activity
gitlab-org/gitlab/-/jobs/123
gitlab-org/gitlab/-/settings/repository
2019-09-30 21:07:59 +05:30
gitlab-org/serverless/runtimes/-/settings/repository
```
2019-09-04 21:01:54 +05:30
2021-09-04 01:27:46 +05:30
## Changing existing routes
Don't change a URL to an existing page, unless it's necessary. If you must make a change,
make it unnoticeable for users, because we don't want them to receive `404 Not Found`
if we can avoid it. This table should help:
| URL description | Example | What to do |
|---|---|---|
| Can be used in scripts and automation | `snippet#raw` | Support both an old and new URL for one major release. Then, support a redirect from an old URL to a new URL for another major release. |
| Likely to be saved or shared | `issue#show` | Add a redirect from an old URL to a new URL until the next major release. |
| Limited use, unlikely to be shared | `admin#labels` | No extra steps required. |
2020-06-23 00:09:42 +05:30
## Migrating unscoped routes
Currently, the majority of routes are placed under the `/-/` scope. However,
you can help us migrate the rest of them! To migrate routes:
2019-09-04 21:01:54 +05:30
1. Modify existing routes by adding `-` scope.
1. Add redirects for legacy routes by using `Gitlab::Routing.redirect_legacy_paths`.
1. Create a technical debt issue to remove deprecated routes in later releases.
2020-03-13 15:44:24 +05:30
To get started, see an [example merge request](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28435).
2020-06-23 00:09:42 +05:30
## Useful links
2022-07-23 23:45:48 +05:30
- [Routing improvements main plan](https://gitlab.com/gitlab-org/gitlab/-/issues/215362)
2020-06-23 00:09:42 +05:30
- [Scoped routing explained](https://gitlab.com/gitlab-org/gitlab/-/issues/214217)
- [Removal of deprecated routes](https://gitlab.com/gitlab-org/gitlab/-/issues/28848)