diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/issues.md | 2 | ||||
-rw-r--r-- | doc/development/api_styleguide.md | 67 |
2 files changed, 68 insertions, 1 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index ef610cc36ad..e466e03f226 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -357,7 +357,7 @@ GET /projects/:id/issues?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the milestone having the given `iid` | +| `iids[]` | integer array | no | Return only the issues having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index e9a41e7ec58..ba926f9f728 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -116,6 +116,73 @@ For instance: - endpoint = expose_path(api_v4_projects_issues_related_merge_requests_path(id: @project.id, issue_iid: @issue.iid)) ``` +## Custom Validators + +In order to validate some parameters in the API request, we validate them +before sending them further (say Gitaly). The following are the +[custom validators](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/validations/validators), +which we have added so far and how to use them. We also wrote a +guide on how you can add a new custom validator. + +### Using custom validators + +- `FilePath`: + + GitLab supports various functionalities where we need to traverse a file path. + The [`FilePath` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/file_path.rb) + validates the parameter value for different cases. Mainly, it checks whether a + path is relative and does it contain `../../` relative traversal using + `File::Separator` or not, and whether the path is absolute, for example + `/etc/passwd/`. + +- `Git SHA`: + + The [`Git SHA` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/git_sha.rb) + checks whether the Git SHA parameter is a valid SHA. + It checks by using the regex mentioned in [`commit.rb`](https://gitlab.com/gitlab-org/gitlab/-/commit/b9857d8b662a2dbbf54f46ecdcecb44702affe55#d1c10892daedb4d4dd3d4b12b6d071091eea83df_30_30) file. + +- `Absence`: + + The [`Absence` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/absence.rb) + checks whether a particular parameter is absent in a given parameters hash. + +- `IntegerNoneAny`: + + The [`IntegerNoneAny` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/integer_none_any.rb) + checks if the value of the given parameter is either an `Integer`, `None`, or `Any`. + It allows only either of these mentioned values to move forward in the request. + +- `ArrayNoneAny`: + + The [`ArrayNoneAny` validator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/array_none_any.rb) + checks if the value of the given parameter is either an `Array`, `None`, or `Any`. + It allows only either of these mentioned values to move forward in the request. + +### Adding a new custom validator + +Custom validators are a great way to validate parameters before sending +them to platform for further processing. It saves some back-and-forth +from the server to the platform if we identify invalid parameters at the beginning. + +If you need to add a custom validator, it would be added to +it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators) directory. +Since we use [Grape](https://github.com/ruby-grape/grape) to add our API +we inherit from the `Grape::Validations::Base` class in our validator class. +Now, all you have to do is define the `validate_param!` method which takes +in two parameters: the `params` hash and the `param` name to validate. + +The body of the method does the hard work of validating the parameter value +and returns appropriate error messages to the caller method. + +Lastly, we register the validator using the line below: + +```ruby +Grape::Validations.register_validator(<validator name as symbol>, ::API::Helpers::CustomValidators::<YourCustomValidatorClassName>) +``` + +Once you add the validator, make sure you add the `rspec`s for it into +it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/api/validations/validators) directory. + ## Internal API The [internal API](./internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints |