1--- 2stage: none 3group: unassigned 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5--- 6 7# GraphQL API style guide 8 9This document outlines the style guide for the GitLab [GraphQL API](../api/graphql/index.md). 10 11## How GitLab implements GraphQL 12 13<!-- vale gitlab.Spelling = NO --> 14 15We use the [GraphQL Ruby gem](https://graphql-ruby.org/) written by [Robert Mosolgo](https://github.com/rmosolgo/). 16In addition, we have a subscription to [GraphQL Pro](https://graphql.pro/). For 17details see [GraphQL Pro subscription](graphql_guide/graphql_pro.md). 18 19<!-- vale gitlab.Spelling = YES --> 20 21All GraphQL queries are directed to a single endpoint 22([`app/controllers/graphql_controller.rb#execute`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app%2Fcontrollers%2Fgraphql_controller.rb)), 23which is exposed as an API endpoint at `/api/graphql`. 24 25## Deep Dive 26 27In March 2019, Nick Thomas hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) 28on the GitLab [GraphQL API](../api/graphql/index.md) to share domain-specific knowledge 29with anyone who may work in this part of the codebase in the future. You can find the 30<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> 31[recording on YouTube](https://www.youtube.com/watch?v=-9L_1MWrjkg), and the slides on 32[Google Slides](https://docs.google.com/presentation/d/1qOTxpkTdHIp1CRjuTvO-aXg0_rUtzE3ETfLUdnBB5uQ/edit) 33and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef649e7d7d569c26d56/GraphQL_Deep_Dive__Create_.pdf). 34Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific 35details may have changed since then, it should still serve as a good introduction. 36 37## GraphiQL 38 39GraphiQL is an interactive GraphQL API explorer where you can play around with existing queries. 40You can access it in any GitLab environment on `https://<your-gitlab-site.com>/-/graphql-explorer`. 41For example, the one for [GitLab.com](https://gitlab.com/-/graphql-explorer). 42 43## Authentication 44 45Authentication happens through the `GraphqlController`, right now this 46uses the same authentication as the Rails application. So the session 47can be shared. 48 49It's also possible to add a `private_token` to the query string, or 50add a `HTTP_PRIVATE_TOKEN` header. 51 52## Limits 53 54Several limits apply to the GraphQL API and some of these can be overridden 55by developers. 56 57### Max page size 58 59By default, [connections](#connection-types) can only return 60at most a maximum number of records defined in 61[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb) 62per page. 63 64Developers can [specify a custom max page size](#page-size-limit) when defining 65a connection. 66 67### Max complexity 68 69Complexity is explained [on our client-facing API page](../api/graphql/index.md#max-query-complexity). 70 71Fields default to adding `1` to a query's complexity score, but developers can 72[specify a custom complexity](#field-complexity) when defining a field. 73 74The complexity score of a query [can itself be queried for](../api/graphql/getting_started.md#query-complexity). 75 76### Request timeout 77 78Requests time out at 30 seconds. 79 80## Breaking changes 81 82The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) which means 83developers must familiarize themselves with our [Deprecation and Removal process](../api/graphql/index.md#deprecation-and-removal-process). 84 85Breaking changes are: 86 87- Removing or renaming a field, argument, enum value, or mutation. 88- Changing the type of a field, argument or enum value. 89- Raising the [complexity](#max-complexity) of a field or complexity multipliers in a resolver. 90- Changing a field from being _not_ nullable (`null: false`) to nullable (`null: true`), as 91discussed in [Nullable fields](#nullable-fields). 92- Changing an argument from being optional (`required: false`) to being required (`required: true`). 93- Changing the [max page size](#page-size-limit) of a connection. 94- Lowering the global limits for query complexity and depth. 95- Anything else that can result in queries hitting a limit that previously was allowed. 96 97Fields that use the [`feature_flag` property](#feature_flag-property) and the flag is disabled by default are exempt 98from the deprecation process, and can be removed at any time without notice. 99 100See the [deprecating fields, arguments, and enum values](#deprecating-fields-arguments-and-enum-values) section for how to deprecate items. 101 102## Global IDs 103 104The GitLab GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`) 105and never database primary key IDs. 106 107Global ID is [a convention](https://graphql.org/learn/global-object-identification/) 108used for caching and fetching in client-side libraries. 109 110See also: 111 112- [Exposing Global IDs](#exposing-global-ids). 113- [Mutation arguments](#object-identifier-arguments). 114- [Deprecating Global IDs](#deprecate-global-ids). 115 116We have a custom scalar type (`Types::GlobalIDType`) which should be used as the 117type of input and output arguments when the value is a `GlobalID`. The benefits 118of using this type instead of `ID` are: 119 120- it validates that the value is a `GlobalID` 121- it parses it into a `GlobalID` before passing it to user code 122- it can be parameterized on the type of the object (for example, 123 `GlobalIDType[Project]`) which offers even better validation and security. 124 125Consider using this type for all new arguments and result types. Remember that 126it is perfectly possible to parameterize this type with a concern or a 127supertype, if you want to accept a wider range of objects (such as 128`GlobalIDType[Issuable]` vs `GlobalIDType[Issue]`). 129 130## Types 131 132We use a code-first schema, and we declare what type everything is in Ruby. 133 134For example, `app/graphql/types/issue_type.rb`: 135 136```ruby 137graphql_name 'Issue' 138 139field :iid, GraphQL::Types::ID, null: true 140field :title, GraphQL::Types::String, null: true 141 142# we also have a method here that we've defined, that extends `field` 143markdown_field :title_html, null: true 144field :description, GraphQL::Types::String, null: true 145markdown_field :description_html, null: true 146``` 147 148We give each type a name (in this case `Issue`). 149 150The `iid`, `title` and `description` are _scalar_ GraphQL types. 151`iid` is a `GraphQL::Types::ID`, a special string type that signifies a unique ID. 152`title` and `description` are regular `GraphQL::Types::String` types. 153 154Note that the old scalar types `GraphQL:ID`, `GraphQL::INT_TYPE`, `GraphQL::STRING_TYPE`, 155`GraphQL:BOOLEAN_TYPE`, and `GraphQL::FLOAT_TYPE` are no longer allowed. Please use `GraphQL::Types::ID`, 156`GraphQL::Types::Int`, `GraphQL::Types::String`, `GraphQL::Types::Boolean`, and `GraphQL::Types::Float`. 157 158When exposing a model through the GraphQL API, we do so by creating a 159new type in `app/graphql/types`. You can also declare custom GraphQL data types 160for scalar data types (for example `TimeType`). 161 162When exposing properties in a type, make sure to keep the logic inside 163the definition as minimal as possible. Instead, consider moving any 164logic into a presenter: 165 166```ruby 167class Types::MergeRequestType < BaseObject 168 present_using MergeRequestPresenter 169 170 name 'MergeRequest' 171end 172``` 173 174An existing presenter could be used, but it is also possible to create 175a new presenter specifically for GraphQL. 176 177The presenter is initialized using the object resolved by a field, and 178the context. 179 180### Nullable fields 181 182GraphQL allows fields to be "nullable" or "non-nullable". The former means 183that `null` may be returned instead of a value of the specified type. **In 184general**, you should prefer using nullable fields to non-nullable ones, for 185the following reasons: 186 187- It's common for data to switch from required to not-required, and back again 188- Even when there is no prospect of a field becoming optional, it may not be **available** at query time 189 - For instance, the `content` of a blob may need to be looked up from Gitaly 190 - If the `content` is nullable, we can return a **partial** response, instead of failing the whole query 191- Changing from a non-nullable field to a nullable field is difficult with a versionless schema 192 193Non-nullable fields should only be used when a field is required, very unlikely 194to become optional in the future, and very easy to calculate. An example would 195be `id` fields. 196 197A non-nullable GraphQL schema field is an object type followed by the exclamation point (bang) `!`. Here's an example from the `gitlab_schema.graphql` file: 198 199```graphql 200 id: ProjectID! 201``` 202 203Here's an example of a non-nullable GraphQL array: 204 205```graphql 206 207 errors: [String!]! 208``` 209 210Further reading: 211 212- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability). 213- GraphQL documentation on [Object types and fields](https://graphql.org/learn/schema/#object-types-and-fields). 214- [GraphQL Best Practices Guide](https://graphql.org/learn/best-practices/#nullability) 215- [Using nullability in GraphQL](https://www.apollographql.com/blog/graphql/basics/using-nullability-in-graphql/) 216 217### Exposing Global IDs 218 219In keeping with the GitLab use of [Global IDs](#global-ids), always convert 220database primary key IDs into Global IDs when you expose them. 221 222All fields named `id` are 223[converted automatically](https://gitlab.com/gitlab-org/gitlab/-/blob/b0f56e7/app/graphql/types/base_object.rb#L11-14) 224into the object's Global ID. 225 226Fields that are not named `id` need to be manually converted. We can do this using 227[`Gitlab::GlobalID.build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/global_id.rb), 228or by calling `#to_global_id` on an object that has mixed in the 229`GlobalID::Identification` module. 230 231Using an example from 232[`Types::Notes::DiscussionType`](https://gitlab.com/gitlab-org/gitlab/-/blob/3c95bd9/app/graphql/types/notes/discussion_type.rb#L24-26): 233 234```ruby 235field :reply_id, GraphQL::Types::ID 236 237def reply_id 238 ::Gitlab::GlobalId.build(object, id: object.reply_id) 239end 240``` 241 242### Connection types 243 244NOTE: 245For specifics on implementation, see [Pagination implementation](#pagination-implementation). 246 247GraphQL uses [cursor based 248pagination](https://graphql.org/learn/pagination/#pagination-and-edges) 249to expose collections of items. This provides the clients with a lot 250of flexibility while also allowing the backend to use different 251pagination models. 252 253To expose a collection of resources we can use a connection type. This wraps the array with default pagination fields. For example a query for project-pipelines could look like this: 254 255```graphql 256query($project_path: ID!) { 257 project(fullPath: $project_path) { 258 pipelines(first: 2) { 259 pageInfo { 260 hasNextPage 261 hasPreviousPage 262 } 263 edges { 264 cursor 265 node { 266 id 267 status 268 } 269 } 270 } 271 } 272} 273``` 274 275This would return the first 2 pipelines of a project and related 276pagination information, ordered by descending ID. The returned data would 277look like this: 278 279```json 280{ 281 "data": { 282 "project": { 283 "pipelines": { 284 "pageInfo": { 285 "hasNextPage": true, 286 "hasPreviousPage": false 287 }, 288 "edges": [ 289 { 290 "cursor": "Nzc=", 291 "node": { 292 "id": "gid://gitlab/Pipeline/77", 293 "status": "FAILED" 294 } 295 }, 296 { 297 "cursor": "Njc=", 298 "node": { 299 "id": "gid://gitlab/Pipeline/67", 300 "status": "FAILED" 301 } 302 } 303 ] 304 } 305 } 306 } 307} 308``` 309 310To get the next page, the cursor of the last known element could be 311passed: 312 313```graphql 314query($project_path: ID!) { 315 project(fullPath: $project_path) { 316 pipelines(first: 2, after: "Njc=") { 317 pageInfo { 318 hasNextPage 319 hasPreviousPage 320 } 321 edges { 322 cursor 323 node { 324 id 325 status 326 } 327 } 328 } 329 } 330} 331``` 332 333To ensure that we get consistent ordering, we append an ordering on the primary 334key, in descending order. This is usually `id`, so we add `order(id: :desc)` 335to the end of the relation. A primary key _must_ be available on the underlying table. 336 337#### Shortcut fields 338 339Sometimes it can seem easy to implement a "shortcut field", having the resolver return the first of a collection if no parameters are passed. 340These "shortcut fields" are discouraged because they create maintenance overhead. 341They need to be kept in sync with their canonical field, and deprecated or modified if their canonical field changes. 342Use the functionality the framework provides unless there is a compelling reason to do otherwise. 343 344For example, instead of `latest_pipeline`, use `pipelines(last: 1)`. 345 346#### Page size limit 347 348By default, the API returns at most a maximum number of records defined in 349[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb) 350per page in a connection and this is also the default number of records 351returned per page if no limiting arguments (`first:` or `last:`) are provided by a client. 352 353The `max_page_size` argument can be used to specify a different page size limit 354for a connection. 355 356WARNING: 357It's better to change the frontend client, or product requirements, to not need large amounts of 358records per page than it is to raise the `max_page_size`, as the default is set to ensure 359the GraphQL API remains performant. 360 361For example: 362 363```ruby 364field :tags, 365 Types::ContainerRepositoryTagType.connection_type, 366 null: true, 367 description: 'Tags of the container repository', 368 max_page_size: 20 369``` 370 371### Field complexity 372 373The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries. 374Complexity is described in [our client documentation](../api/graphql/index.md#max-query-complexity) on the topic. 375 376Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb). 377 378By default, fields add `1` to a query's complexity score. This can be overridden by 379[providing a custom `complexity`](https://graphql-ruby.org/queries/complexity_and_depth.html) value for a field. 380 381Developers should specify higher complexity for fields that cause more _work_ to be performed 382by the server in order to return data. Fields that represent data that can be returned 383with little-to-no _work_, for example in most cases; `id` or `title`, can be given a complexity of `0`. 384 385### `calls_gitaly` 386 387Fields that have the potential to perform a [Gitaly](../administration/gitaly/index.md) call when resolving _must_ be marked as 388such by passing `calls_gitaly: true` to `field` when defining it. 389 390For example: 391 392```ruby 393field :blob, type: Types::Snippets::BlobType, 394 description: 'Snippet blob', 395 null: false, 396 calls_gitaly: true 397``` 398 399This increments the [`complexity` score](#field-complexity) of the field by `1`. 400 401If a resolver calls Gitaly, it can be annotated with 402`BaseResolver.calls_gitaly!`. This passes `calls_gitaly: true` to any 403field that uses this resolver. 404 405For example: 406 407```ruby 408class BranchResolver < BaseResolver 409 type ::Types::BranchType, null: true 410 calls_gitaly! 411 412 argument name: ::GraphQL::Types::String, required: true 413 414 def resolve(name:) 415 object.branch(name) 416 end 417end 418``` 419 420Then when we use it, any field that uses `BranchResolver` has the correct 421value for `calls_gitaly:`. 422 423### Exposing permissions for a type 424 425To expose permissions the current user has on a resource, you can call 426the `expose_permissions` passing in a separate type representing the 427permissions for the resource. 428 429For example: 430 431```ruby 432module Types 433 class MergeRequestType < BaseObject 434 expose_permissions Types::MergeRequestPermissionsType 435 end 436end 437``` 438 439The permission type inherits from `BasePermissionType` which includes 440some helper methods, that allow exposing permissions as non-nullable 441booleans: 442 443```ruby 444class MergeRequestPermissionsType < BasePermissionType 445 present_using MergeRequestPresenter 446 447 graphql_name 'MergeRequestPermissions' 448 449 abilities :admin_merge_request, :update_merge_request, :create_note 450 451 ability_field :resolve_note, 452 description: 'Indicates the user can resolve discussions on the merge request.' 453 permission_field :push_to_source_branch, method: :can_push_to_source_branch? 454end 455``` 456 457- **`permission_field`**: Acts the same as `graphql-ruby`'s 458 `field` method but setting a default description and type and making 459 them non-nullable. These options can still be overridden by adding 460 them as arguments. 461- **`ability_field`**: Expose an ability defined in our policies. This 462 behaves the same way as `permission_field` and the same 463 arguments can be overridden. 464- **`abilities`**: Allows exposing several abilities defined in our 465 policies at once. The fields for these must all be non-nullable 466 booleans with a default description. 467 468## Feature flags 469 470Developers can add [feature flags](../development/feature_flags/index.md) to GraphQL 471fields in the following ways: 472 473- Add the `feature_flag` property to a field. This allows the field to be _hidden_ 474 from the GraphQL schema when the flag is disabled. 475- Toggle the return value when resolving the field. 476 477You can refer to these guidelines to decide which approach to use: 478 479- If your field is experimental, and its name or type is subject to 480 change, use the `feature_flag` property. 481- If your field is stable and its definition doesn't change, even after the flag is 482 removed, toggle the return value of the field instead. Note that 483 [all fields should be nullable](#nullable-fields) anyway. 484 485### `feature_flag` property 486 487The `feature_flag` property allows you to toggle the field's 488[visibility](https://graphql-ruby.org/authorization/visibility.html) 489in the GraphQL schema. This removes the field from the schema 490when the flag is disabled. 491 492A description is [appended](https://gitlab.com/gitlab-org/gitlab/-/blob/497b556/app/graphql/types/base_field.rb#L44-53) 493to the field indicating that it is behind a feature flag. 494 495WARNING: 496If a client queries for the field when the feature flag is disabled, the query 497fails. Consider this when toggling the visibility of the feature on or off on 498production. 499 500The `feature_flag` property does not allow the use of 501[feature gates based on actors](../development/feature_flags/index.md). 502This means that the feature flag cannot be toggled only for particular 503projects, groups, or users, but instead can only be toggled globally for 504everyone. 505 506Example: 507 508```ruby 509field :test_field, type: GraphQL::Types::String, 510 null: true, 511 description: 'Some test field.', 512 feature_flag: :my_feature_flag 513``` 514 515### Toggle the value of a field 516 517This method of using feature flags for fields is to toggle the 518return value of the field. This can be done in the resolver, in the 519type, or even in a model method, depending on your preference and 520situation. 521 522When applying a feature flag to toggle the value of a field, the 523`description` of the field must: 524 525- State that the value of the field can be toggled by a feature flag. 526- Name the feature flag. 527- State what the field returns when the feature flag is disabled (or 528 enabled, if more appropriate). 529 530Example: 531 532```ruby 533field :foo, GraphQL::Types::String, 534 null: true, 535 description: 'Some test field. Returns `null`' \ 536 'if `my_feature_flag` feature flag is disabled.' 537 538def foo 539 object.foo if Feature.enabled?(:my_feature_flag, object) 540end 541``` 542 543## Deprecating fields, arguments, and enum values 544 545The GitLab GraphQL API is versionless, which means we maintain backwards 546compatibility with older versions of the API with every change. 547 548Rather than removing fields, arguments, or [enum values](#enums), they 549must be _deprecated_ instead. 550 551The deprecated parts of the schema can then be removed in a future release 552in accordance with the [GitLab deprecation process](../api/graphql/index.md#deprecation-and-removal-process). 553 554Fields, arguments, and enum values are deprecated using the `deprecated` property. 555The value of the property is a `Hash` of: 556 557- `reason` - Reason for the deprecation. 558- `milestone` - Milestone that the field was deprecated. 559 560Example: 561 562```ruby 563field :token, GraphQL::Types::String, null: true, 564 deprecated: { reason: 'Login via token has been removed', milestone: '10.0' }, 565 description: 'Token for login.' 566``` 567 568The original `description` of the things being deprecated should be maintained, 569and should _not_ be updated to mention the deprecation. Instead, the `reason` 570is appended to the `description`. 571 572### Deprecation reason style guide 573 574Where the reason for deprecation is due to the field, argument, or enum value being 575replaced, the `reason` must indicate the replacement. For example, the 576following is a `reason` for a replaced field: 577 578```plaintext 579Use `otherFieldName` 580``` 581 582Examples: 583 584```ruby 585field :designs, ::Types::DesignManagement::DesignCollectionType, null: true, 586 deprecated: { reason: 'Use `designCollection`', milestone: '10.0' }, 587 description: 'The designs associated with this issue.', 588``` 589 590```ruby 591module Types 592 class TodoStateEnum < BaseEnum 593 value 'pending', deprecated: { reason: 'Use PENDING', milestone: '10.0' } 594 value 'done', deprecated: { reason: 'Use DONE', milestone: '10.0' } 595 value 'PENDING', value: 'pending' 596 value 'DONE', value: 'done' 597 end 598end 599``` 600 601If the field, argument, or enum value being deprecated is not being replaced, 602a descriptive deprecation `reason` should be given. 603 604### Deprecate Global IDs 605 606We use the [`rails/globalid`](https://github.com/rails/globalid) gem to generate and parse 607Global IDs, so as such they are coupled to model names. When we rename a 608model, its Global ID changes. 609 610If the Global ID is used as an _argument_ type anywhere in the schema, then the Global ID 611change would normally constitute a breaking change. 612 613To continue to support clients using the old Global ID argument, we add a deprecation 614to `Gitlab::GlobalId::Deprecations`. 615 616NOTE: 617If the Global ID is _only_ [exposed as a field](#exposing-global-ids) then we do not need to 618deprecate it. We consider the change to the way a Global ID is expressed in a field to be 619backwards-compatible. We expect that clients don't parse these values: they are meant to 620be treated as opaque tokens, and any structure in them is incidental and not to be relied on. 621 622**Example scenario:** 623 624This example scenario is based on this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62645). 625 626A model named `PrometheusService` is to be renamed `Integrations::Prometheus`. The old model 627name is used to create a Global ID type that is used as an argument for a mutation: 628 629```ruby 630# Mutations::UpdatePrometheus: 631 632argument :id, Types::GlobalIDType[::PrometheusService], 633 required: true, 634 description: "The ID of the integration to mutate." 635``` 636 637Clients call the mutation by passing a Global ID string that looks like 638`"gid://gitlab/PrometheusService/1"`, named as `PrometheusServiceID`, as the `input.id` argument: 639 640```graphql 641mutation updatePrometheus($id: PrometheusServiceID!, $active: Boolean!) { 642 prometheusIntegrationUpdate(input: { id: $id, active: $active }) { 643 errors 644 integration { 645 active 646 } 647 } 648} 649``` 650 651We rename the model to `Integrations::Prometheus`, and then update the codebase with the new name. 652When we come to update the mutation, we pass the renamed model to `Types::GlobalIDType[]`: 653 654```ruby 655# Mutations::UpdatePrometheus: 656 657argument :id, Types::GlobalIDType[::Integrations::Prometheus], 658 required: true, 659 description: "The ID of the integration to mutate." 660``` 661 662This would cause a breaking change to the mutation, as the API now rejects clients who 663pass an `id` argument as `"gid://gitlab/PrometheusService/1"`, or that specify the argument 664type as `PrometheusServiceID` in the query signature. 665 666To allow clients to continue to interact with the mutation unchanged, edit the `DEPRECATIONS` constant in 667`Gitlab::GlobalId::Deprecations` and add a new `Deprecation` to the array: 668 669```ruby 670DEPRECATIONS = [ 671 Deprecation.new(old_model_name: 'PrometheusService', new_model_name: 'Integrations::Prometheus', milestone: '14.0') 672].freeze 673``` 674 675Then follow our regular [deprecation process](../api/graphql/index.md#deprecation-and-removal-process). To later remove 676support for the former argument style, remove the `Deprecation`: 677 678```ruby 679DEPRECATIONS = [].freeze 680``` 681 682During the deprecation period the API will accept either of these formats for the argument value: 683 684- `"gid://gitlab/PrometheusService/1"` 685- `"gid://gitlab/Integrations::Prometheus/1"` 686 687The API will also accept these types in the query signature for the argument: 688 689- `PrometheusServiceID` 690- `IntegrationsPrometheusID` 691 692NOTE: 693Although queries that use the old type (`PrometheusServiceID` in this example) will be 694considered valid and executable by the API, validator tools will consider them to be invalid. 695This is because we are deprecating using a bespoke method outside of the 696[`@deprecated` directive](https://spec.graphql.org/June2018/#sec--deprecated), so validators are not 697aware of the support. 698 699The documentation will mention that the old Global ID style is now deprecated. 700 701See also: 702 703- [Aliasing and deprecating mutations](#aliasing-and-deprecating-mutations). 704- [How to filter Kibana for queries that used deprecated fields](graphql_guide/monitoring.md#queries-that-used-a-deprecated-field). 705 706## Enums 707 708GitLab GraphQL enums are defined in `app/graphql/types`. When defining new enums, the 709following rules apply: 710 711- Values must be uppercase. 712- Class names must end with the string `Enum`. 713- The `graphql_name` must not contain the string `Enum`. 714 715For example: 716 717```ruby 718module Types 719 class TrafficLightStateEnum < BaseEnum 720 graphql_name 'TrafficLightState' 721 description 'State of a traffic light' 722 723 value 'RED', description: 'Drivers must stop.' 724 value 'YELLOW', description: 'Drivers must stop when it is safe to.' 725 value 'GREEN', description: 'Drivers can start or keep driving.' 726 end 727end 728``` 729 730If the enum is used for a class property in Ruby that is not an uppercase string, 731you can provide a `value:` option that adapts the uppercase value. 732 733In the following example: 734 735- GraphQL inputs of `OPENED` are converted to `'opened'`. 736- Ruby values of `'opened'` are converted to `"OPENED"` in GraphQL responses. 737 738```ruby 739module Types 740 class EpicStateEnum < BaseEnum 741 graphql_name 'EpicState' 742 description 'State of a GitLab epic' 743 744 value 'OPENED', value: 'opened', description: 'An open Epic.' 745 value 'CLOSED', value: 'closed', description: 'A closed Epic.' 746 end 747end 748``` 749 750Enum values can be deprecated using the 751[`deprecated` keyword](#deprecating-fields-arguments-and-enum-values). 752 753### Defining GraphQL enums dynamically from Rails enums 754 755If your GraphQL enum is backed by a [Rails enum](creating_enums.md), then consider 756using the Rails enum to dynamically define the GraphQL enum values. Doing so 757binds the GraphQL enum values to the Rails enum definition, so if values are 758ever added to the Rails enum then the GraphQL enum automatically reflects the change. 759 760Example: 761 762```ruby 763module Types 764 class IssuableSeverityEnum < BaseEnum 765 graphql_name 'IssuableSeverity' 766 description 'Incident severity' 767 768 ::IssuableSeverity.severities.keys.each do |severity| 769 value severity.upcase, value: severity, description: "#{severity.titleize} severity." 770 end 771 end 772end 773``` 774 775## JSON 776 777When data to be returned by GraphQL is stored as 778[JSON](migration_style_guide.md#storing-json-in-database), we should continue to use 779GraphQL types whenever possible. Avoid using the `GraphQL::Types::JSON` type unless 780the JSON data returned is _truly_ unstructured. 781 782If the structure of the JSON data varies, but is one of a set of known possible 783structures, use a 784[union](https://graphql-ruby.org/type_definitions/unions.html). 785An example of the use of a union for this purpose is 786[!30129](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30129). 787 788Field names can be mapped to hash data keys using the `hash_key:` keyword if needed. 789 790For example, given the following simple JSON data: 791 792```json 793{ 794 "title": "My chart", 795 "data": [ 796 { "x": 0, "y": 1 }, 797 { "x": 1, "y": 1 }, 798 { "x": 2, "y": 2 } 799 ] 800} 801``` 802 803We can use GraphQL types like this: 804 805```ruby 806module Types 807 class ChartType < BaseObject 808 field :title, GraphQL::Types::String, null: true, description: 'Title of the chart.' 809 field :data, [Types::ChartDatumType], null: true, description: 'Data of the chart.' 810 end 811end 812 813module Types 814 class ChartDatumType < BaseObject 815 field :x, GraphQL::Types::Int, null: true, description: 'X-axis value of the chart datum.' 816 field :y, GraphQL::Types::Int, null: true, description: 'Y-axis value of the chart datum.' 817 end 818end 819``` 820 821## Descriptions 822 823All fields and arguments 824[must have descriptions](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16438). 825 826A description of a field or argument is given using the `description:` 827keyword. For example: 828 829```ruby 830field :id, GraphQL::Types::ID, description: 'ID of the resource.' 831``` 832 833Descriptions of fields and arguments are viewable to users through: 834 835- The [GraphiQL explorer](#graphiql). 836- The [static GraphQL API reference](../api/graphql/reference/index.md). 837 838### Description style guide 839 840To ensure consistency, the following should be followed whenever adding or updating 841descriptions: 842 843- Mention the name of the resource in the description. Example: 844 `'Labels of the issue'` (issue being the resource). 845- Use `"{x} of the {y}"` where possible. Example: `'Title of the issue'`. 846 Do not start descriptions with `The` or `A`, for consistency and conciseness. 847- Descriptions of `GraphQL::Types::Boolean` fields should answer the question: "What does 848 this field do?". Example: `'Indicates project has a Git repository'`. 849- Always include the word `"timestamp"` when describing an argument or 850 field of type `Types::TimeType`. This lets the reader know that the 851 format of the property is `Time`, rather than just `Date`. 852- Must end with a period (`.`). 853 854Example: 855 856```ruby 857field :id, GraphQL::Types::ID, description: 'ID of the issue.' 858field :confidential, GraphQL::Types::Boolean, description: 'Indicates the issue is confidential.' 859field :closed_at, Types::TimeType, description: 'Timestamp of when the issue was closed.' 860``` 861 862### `copy_field_description` helper 863 864Sometimes we want to ensure that two descriptions are always identical. 865For example, to keep a type field description the same as a mutation argument 866when they both represent the same property. 867 868Instead of supplying a description, we can use the `copy_field_description` helper, 869passing it the type, and field name to copy the description of. 870 871Example: 872 873```ruby 874argument :title, GraphQL::Types::String, 875 required: false, 876 description: copy_field_description(Types::MergeRequestType, :title) 877``` 878 879### Documentation references 880 881Sometimes we want to refer to external URLs in our descriptions. To make this 882easier, and provide proper markup in the generated reference documentation, we 883provide a `see` property on fields. For example: 884 885```ruby 886field :genus, 887 type: GraphQL::Types::String, 888 null: true, 889 description: 'A taxonomic genus.' 890 see: { 'Wikipedia page on genera' => 'https://wikipedia.org/wiki/Genus' } 891``` 892 893This renders in our documentation as: 894 895```markdown 896A taxonomic genus. See: [Wikipedia page on genera](https://wikipedia.org/wiki/Genus) 897``` 898 899Multiple documentation references can be provided. The syntax for this property 900is a `HashMap` where the keys are textual descriptions, and the values are URLs. 901 902## Authorization 903 904See: [GraphQL Authorization](graphql_guide/authorization.md) 905 906## Resolvers 907 908We define how the application serves the response using _resolvers_ 909stored in the `app/graphql/resolvers` directory. 910The resolver provides the actual implementation logic for retrieving 911the objects in question. 912 913To find objects to display in a field, we can add resolvers to 914`app/graphql/resolvers`. 915 916Arguments can be defined within the resolver in the same way as in a mutation. 917See the [Mutation arguments](#object-identifier-arguments) section. 918 919To limit the amount of queries performed, we can use [BatchLoader](graphql_guide/batchloader.md). 920 921### Writing resolvers 922 923Our code should aim to be thin declarative wrappers around finders and [services](../development/reusing_abstractions.md#service-classes). You can 924repeat lists of arguments, or extract them to concerns. Composition is preferred over 925inheritance in most cases. Treat resolvers like controllers: resolvers should be a DSL 926that compose other application abstractions. 927 928For example: 929 930```ruby 931class PostResolver < BaseResolver 932 type Post.connection_type, null: true 933 authorize :read_blog 934 description 'Blog posts, optionally filtered by name' 935 936 argument :name, [::GraphQL::Types::String], required: false, as: :slug 937 938 alias_method :blog, :object 939 940 def resolve(**args) 941 PostFinder.new(blog, current_user, args).execute 942 end 943end 944``` 945 946While you can use the same resolver class in two different places, 947such as in two different fields where the same object is exposed, 948you should never re-use resolver objects directly. Resolvers have a complex life-cycle, with 949authorization, readiness and resolution orchestrated by the framework, and at 950each stage [lazy values](#laziness) can be returned to take advantage of batching 951opportunities. Never instantiate a resolver or a mutation in application code. 952 953Instead, the units of code reuse are much the same as in the rest of the 954application: 955 956- Finders in queries to look up data. 957- Services in mutations to apply operations. 958- Loaders (batch-aware finders) specific to queries. 959 960Note that there is never any reason to use batching in a mutation. Mutations are 961executed in series, so there are no batching opportunities. All values are 962evaluated eagerly as soon as they are requested, so batching is unnecessary 963overhead. If you are writing: 964 965- A `Mutation`, feel free to lookup objects directly. 966- A `Resolver` or methods on a `BaseObject`, then you want to allow for batching. 967 968### Error handling 969 970Resolvers may raise errors, which are converted to top-level errors as 971appropriate. All anticipated errors should be caught and transformed to an 972appropriate GraphQL error (see 973[`Gitlab::Graphql::Errors`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/errors.rb)). 974Any uncaught errors are suppressed and the client receives the message 975`Internal service error`. 976 977The one special case is permission errors. In the REST API we return 978`404 Not Found` for any resources that the user does not have permission to 979access. The equivalent behavior in GraphQL is for us to return `null` for 980all absent or unauthorized resources. 981Query resolvers **should not raise errors for unauthorized resources**. 982 983The rationale for this is that clients must not be able to distinguish between 984the absence of a record and the presence of one they do not have access to. To 985do so is a security vulnerability, because it leaks information we want to keep 986hidden. 987 988In most cases you don't need to worry about this - this is handled correctly by 989the resolver field authorization we declare with the `authorize` DSL calls. If 990you need to do something more custom however, remember, if you encounter an 991object the `current_user` does not have access to when resolving a field, then 992the entire field should resolve to `null`. 993 994### Deriving resolvers (`BaseResolver.single` and `BaseResolver.last`) 995 996For some simple use cases, we can derive resolvers from others. 997The main use case for this is one resolver to find all items, and another to 998find one specific one. For this, we supply convenience methods: 999 1000- `BaseResolver.single`, which constructs a new resolver that selects the first item. 1001- `BaseResolver.last`, which constructs a resolver that selects the last item. 1002 1003The correct singular type is inferred from the collection type, so we don't have 1004to define the `type` here. 1005 1006Before you make use of these methods, consider if it would be simpler to either: 1007 1008- Write another resolver that defines its own arguments. 1009- Write a concern that abstracts out the query. 1010 1011Using `BaseResolver.single` too freely is an anti-pattern. It can lead to 1012non-sensical fields, such as a `Project.mergeRequest` field that just returns 1013the first MR if no arguments are given. Whenever we derive a single resolver 1014from a collection resolver, it must have more restrictive arguments. 1015 1016To make this possible, use the `when_single` block to customize the single 1017resolver. Every `when_single` block must: 1018 1019- Define (or re-define) at least one argument. 1020- Make optional filters required. 1021 1022For example, we can do this by redefining an existing optional argument, 1023changing its type and making it required: 1024 1025```ruby 1026class JobsResolver < BaseResolver 1027 type JobType.connection_type, null: true 1028 authorize :read_pipeline 1029 1030 argument :name, [::GraphQL::Types::String], required: false 1031 1032 when_single do 1033 argument :name, ::GraphQL::Types::String, required: true 1034 end 1035 1036 def resolve(**args) 1037 JobsFinder.new(pipeline, current_user, args.compact).execute 1038 end 1039``` 1040 1041Here we have a simple resolver for getting pipeline jobs. The `name` argument is 1042optional when getting a list, but required when getting a single job. 1043 1044If there are multiple arguments, and neither can be made required, we can use 1045the block to add a ready condition: 1046 1047```ruby 1048class JobsResolver < BaseResolver 1049 alias_method :pipeline, :object 1050 1051 type JobType.connection_type, null: true 1052 authorize :read_pipeline 1053 1054 argument :name, [::GraphQL::Types::String], required: false 1055 argument :id, [::Types::GlobalIDType[::Job]], 1056 required: false, 1057 prepare: ->(ids, ctx) { ids.map(&:model_id) } 1058 1059 when_single do 1060 argument :name, ::GraphQL::Types::String, required: false 1061 argument :id, ::Types::GlobalIDType[::Job], 1062 required: false 1063 prepare: ->(id, ctx) { id.model_id } 1064 1065 def ready?(**args) 1066 raise ::Gitlab::Graphql::Errors::ArgumentError, 'Only one argument may be provided' unless args.size == 1 1067 end 1068 end 1069 1070 def resolve(**args) 1071 JobsFinder.new(pipeline, current_user, args.compact).execute 1072 end 1073``` 1074 1075Then we can use these resolver on fields: 1076 1077```ruby 1078# In PipelineType 1079 1080field :jobs, resolver: JobsResolver, description: 'All jobs.' 1081field :job, resolver: JobsResolver.single, description: 'A single job.' 1082``` 1083 1084### Correct use of `Resolver#ready?` 1085 1086Resolvers have two public API methods as part of the framework: `#ready?(**args)` and `#resolve(**args)`. 1087We can use `#ready?` to perform set-up, validation or early-return without invoking `#resolve`. 1088 1089Good reasons to use `#ready?` include: 1090 1091- validating mutually exclusive arguments (see [validating arguments](#validating-arguments)) 1092- Returning `Relation.none` if we know before-hand that no results are possible 1093- Performing setup such as initializing instance variables (although consider lazily initialized methods for this) 1094 1095Implementations of [`Resolver#ready?(**args)`](https://graphql-ruby.org/api-doc/1.10.9/GraphQL/Schema/Resolver#ready%3F-instance_method) should 1096return `(Boolean, early_return_data)` as follows: 1097 1098```ruby 1099def ready?(**args) 1100 [false, 'have this instead'] 1101end 1102``` 1103 1104For this reason, whenever you call a resolver (mainly in tests - as framework 1105abstractions Resolvers should not be considered re-usable, finders are to be 1106preferred), remember to call the `ready?` method and check the boolean flag 1107before calling `resolve`! An example can be seen in our [`GraphqlHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27). 1108 1109### Look-Ahead 1110 1111The full query is known in advance during execution, which means we can make use 1112of [lookahead](https://graphql-ruby.org/queries/lookahead.html) to optimize our 1113queries, and batch load associations we know we need. Consider adding 1114lookahead support in your resolvers to avoid `N+1` performance issues. 1115 1116To enable support for common lookahead use-cases (pre-loading associations when 1117child fields are requested), you can 1118include [`LooksAhead`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/looks_ahead.rb). For example: 1119 1120```ruby 1121# Assuming a model `MyThing` with attributes `[child_attribute, other_attribute, nested]`, 1122# where nested has an attribute named `included_attribute`. 1123class MyThingResolver < BaseResolver 1124 include LooksAhead 1125 1126 # Rather than defining `resolve(**args)`, we implement: `resolve_with_lookahead(**args)` 1127 def resolve_with_lookahead(**args) 1128 apply_lookahead(MyThingFinder.new(current_user).execute) 1129 end 1130 1131 # We list things that should always be preloaded: 1132 # For example, if child_attribute is always needed (during authorization 1133 # perhaps), then we can include it here. 1134 def unconditional_includes 1135 [:child_attribute] 1136 end 1137 1138 # We list things that should be included if a certain field is selected: 1139 def preloads 1140 { 1141 field_one: [:other_attribute], 1142 field_two: [{ nested: [:included_attribute] }] 1143 } 1144 end 1145end 1146``` 1147 1148By default, fields defined in `#preloads` are preloaded if that field 1149is selected in the query. Occasionally, finer control may be 1150needed to avoid preloading too much or incorrect content. 1151 1152Extending the above example, we might want to preload a different 1153association if certain fields are requested together. This can 1154be done by overriding `#filtered_preloads`: 1155 1156```ruby 1157class MyThingResolver < BaseResolver 1158 # ... 1159 1160 def filtered_preloads 1161 return [:alternate_attribute] if lookahead.selects?(:field_one) && lookahead.selects?(:field_two) 1162 1163 super 1164 end 1165end 1166``` 1167 1168The final thing that is needed is that every field that uses this resolver needs 1169to advertise the need for lookahead: 1170 1171```ruby 1172 # in ParentType 1173 field :my_things, MyThingType.connection_type, null: true, 1174 extras: [:lookahead], # Necessary 1175 resolver: MyThingResolver, 1176 description: 'My things.' 1177``` 1178 1179For an example of real world use, please 1180see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb). 1181 1182### Negated arguments 1183 1184Negated filters can filter some resources (for example, find all issues that 1185have the `bug` label, but don't have the `bug2` label assigned). The `not` 1186argument is the preferred syntax to pass negated arguments: 1187 1188```graphql 1189issues(labelName: "bug", not: {labelName: "bug2"}) { 1190 nodes { 1191 id 1192 title 1193 } 1194} 1195``` 1196 1197To avoid duplicated argument definitions, you can place these arguments in a reusable module (or 1198class, if the arguments are nested). Alternatively, you can consider to add a 1199[helper resolver method](https://gitlab.com/gitlab-org/gitlab/-/issues/258969). 1200 1201### Metadata 1202 1203When using resolvers, they can and should serve as the SSoT for field metadata. 1204All field options (apart from the field name) can be declared on the resolver. 1205These include: 1206 1207- `type` (required - all resolvers must include a type annotation) 1208- `extras` 1209- `description` 1210- Gitaly annotations (with `calls_gitaly!`) 1211 1212Example: 1213 1214```ruby 1215module Resolvers 1216 MyResolver < BaseResolver 1217 type Types::MyType, null: true 1218 extras [:lookahead] 1219 description 'Retrieve a single MyType' 1220 calls_gitaly! 1221 end 1222end 1223``` 1224 1225### Pass a parent object into a child Presenter 1226 1227Sometimes you need to access the resolved query parent in a child context to compute fields. Usually the parent is only 1228available in the `Resolver` class as `parent`. 1229 1230To find the parent object in your `Presenter` class: 1231 12321. Add the parent object to the GraphQL `context` from your resolver's `resolve` method: 1233 1234 ```ruby 1235 def resolve(**args) 1236 context[:parent_object] = parent 1237 end 1238 ``` 1239 12401. Declare that your resolver or fields require the `parent` field context. For example: 1241 1242 ```ruby 1243 # in ChildType 1244 field :computed_field, SomeType, null: true, 1245 method: :my_computing_method, 1246 extras: [:parent], # Necessary 1247 description: 'My field description.' 1248 1249 field :resolver_field, resolver: SomeTypeResolver 1250 1251 # In SomeTypeResolver 1252 1253 extras [:parent] 1254 type SomeType, null: true 1255 description 'My field description.' 1256 ``` 1257 12581. Declare your field's method in your Presenter class and have it accept the `parent` keyword argument. 1259This argument contains the parent **GraphQL context**, so you have to access the parent object with 1260`parent[:parent_object]` or whatever key you used in your `Resolver`: 1261 1262 ```ruby 1263 # in ChildPresenter 1264 def my_computing_method(parent:) 1265 # do something with `parent[:parent_object]` here 1266 end 1267 1268 # In SomeTypeResolver 1269 1270 def resolve(parent:) 1271 # ... 1272 end 1273 ``` 1274 1275For an example of real-world use, check [this MR that added `scopedPath` and `scopedUrl` to `IterationPresenter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39543) 1276 1277## Mutations 1278 1279Mutations are used to change any stored values, or to trigger 1280actions. In the same way a GET-request should not modify data, we 1281cannot modify data in a regular GraphQL-query. We can however in a 1282mutation. 1283 1284### Building Mutations 1285 1286Mutations are stored in `app/graphql/mutations`, ideally grouped per 1287resources they are mutating, similar to our services. They should 1288inherit `Mutations::BaseMutation`. The fields defined on the mutation 1289are returned as the result of the mutation. 1290 1291#### Update mutation granularity 1292 1293The service-oriented architecture in GitLab means that most mutations call a Create, Delete, or Update 1294service, for example `UpdateMergeRequestService`. 1295For Update mutations, you might want to only update one aspect of an object, and thus only need a 1296_fine-grained_ mutation, for example `MergeRequest::SetDraft`. 1297 1298It's acceptable to have both fine-grained mutations and coarse-grained mutations, but be aware 1299that too many fine-grained mutations can lead to organizational challenges in maintainability, code 1300comprehensibility, and testing. 1301Each mutation requires a new class, which can lead to technical debt. 1302It also means the schema becomes very big, and we want users to easily navigate our schema. 1303As each new mutation also needs tests (including slower request integration tests), adding mutations 1304slows down the test suite. 1305 1306To minimize changes: 1307 1308- Use existing mutations, such as `MergeRequest::Update`, when available. 1309- Expose existing services as a coarse-grained mutation. 1310 1311When a fine-grained mutation might be more appropriate: 1312 1313- Modifying a property that requires specific permissions or other specialized logic. 1314- Exposing a state-machine-like transition (locking issues, merging MRs, closing epics, etc). 1315- Accepting nested properties (where we accept properties for a child object). 1316- The semantics of the mutation can be expressed clearly and concisely. 1317 1318See [issue #233063](https://gitlab.com/gitlab-org/gitlab/-/issues/233063) for further context. 1319 1320### Naming conventions 1321 1322Each mutation must define a `graphql_name`, which is the name of the mutation in the GraphQL schema. 1323 1324Example: 1325 1326```ruby 1327class UserUpdateMutation < BaseMutation 1328 graphql_name 'UserUpdate' 1329end 1330``` 1331 1332Our GraphQL mutation names are historically inconsistent, but new mutation names should follow the 1333convention `'{Resource}{Action}'` or `'{Resource}{Action}{Attribute}'`. 1334 1335Mutations that **create** new resources should use the verb `Create`. 1336 1337Example: 1338 1339- `CommitCreate` 1340 1341Mutations that **update** data should use: 1342 1343- The verb `Update`. 1344- A domain-specific verb like `Set`, `Add`, or `Toggle` if more appropriate. 1345 1346Examples: 1347 1348- `EpicTreeReorder` 1349- `IssueSetWeight` 1350- `IssueUpdate` 1351- `TodoMarkDone` 1352 1353Mutations that **remove** data should use: 1354 1355- The verb `Delete` rather than `Destroy`. 1356- A domain-specific verb like `Remove` if more appropriate. 1357 1358Examples: 1359 1360- `AwardEmojiRemove` 1361- `NoteDelete` 1362 1363If you need advice for mutation naming, canvass the Slack `#graphql` channel for feedback. 1364 1365### Arguments 1366 1367Arguments for a mutation are defined using `argument`. 1368 1369Example: 1370 1371```ruby 1372argument :my_arg, GraphQL::Types::String, 1373 required: true, 1374 description: "A description of the argument." 1375``` 1376 1377#### Nullability 1378 1379Arguments can be marked as `required: true` which means the value must be present and not `null`. 1380If a required argument's value can be `null`, use the `required: :nullable` declaration. 1381 1382Example: 1383 1384```ruby 1385argument :due_date, 1386 Types::TimeType, 1387 required: :nullable, 1388 description: 'The desired due date for the issue. Due date is removed if null.' 1389``` 1390 1391In the above example, the `due_date` argument must be given, but unlike the GraphQL spec, the value can be `null`. 1392This allows 'unsetting' the due date in a single mutation rather than creating a new mutation for removing the due date. 1393 1394```ruby 1395{ due_date: null } # => OK 1396{ due_date: "2025-01-10" } # => OK 1397{ } # => invalid (not given) 1398``` 1399 1400#### Keywords 1401 1402Each GraphQL `argument` defined is passed to the `#resolve` method 1403of a mutation as keyword arguments. 1404 1405Example: 1406 1407```ruby 1408def resolve(my_arg:) 1409 # Perform mutation ... 1410end 1411``` 1412 1413#### Input Types 1414 1415`graphql-ruby` wraps up arguments into an 1416[input type](https://graphql.org/learn/schema/#input-types). 1417 1418For example, the 1419[`mergeRequestSetDraft` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_draft.rb) 1420defines these arguments (some 1421[through inheritance](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/base.rb)): 1422 1423```ruby 1424argument :project_path, GraphQL::Types::ID, 1425 required: true, 1426 description: "The project the merge request to mutate is in." 1427 1428argument :iid, GraphQL::Types::String, 1429 required: true, 1430 description: "The IID of the merge request to mutate." 1431 1432argument :draft, 1433 GraphQL::Types::Boolean, 1434 required: false, 1435 description: <<~DESC 1436 Whether or not to set the merge request as a draft. 1437 DESC 1438``` 1439 1440These arguments automatically generate an input type called 1441`MergeRequestSetDraftInput` with the 3 arguments we specified and the 1442`clientMutationId`. 1443 1444### Object identifier arguments 1445 1446In keeping with the GitLab use of [Global IDs](#global-ids), mutation 1447arguments should use Global IDs to identify an object and never database 1448primary key IDs. 1449 1450Where an object has an `iid`, prefer to use the `full_path` or `group_path` 1451of its parent in combination with its `iid` as arguments to identify an 1452object rather than its `id`. 1453 1454See also [Deprecate Global IDs](#deprecate-global-ids). 1455 1456### Fields 1457 1458In the most common situations, a mutation would return 2 fields: 1459 1460- The resource being modified 1461- A list of errors explaining why the action could not be 1462 performed. If the mutation succeeded, this list would be empty. 1463 1464By inheriting any new mutations from `Mutations::BaseMutation` the 1465`errors` field is automatically added. A `clientMutationId` field is 1466also added, this can be used by the client to identify the result of a 1467single mutation when multiple are performed in a single request. 1468 1469### The `resolve` method 1470 1471Similar to [writing resolvers](#writing-resolvers), the `resolve` method of a mutation 1472should aim to be a thin declarative wrapper around a 1473[service](../development/reusing_abstractions.md#service-classes). 1474 1475The `resolve` method receives the mutation's arguments as keyword arguments. 1476From here, we can call the service that modifies the resource. 1477 1478The `resolve` method should then return a hash with the same field 1479names as defined on the mutation including an `errors` array. For example, 1480the `Mutations::MergeRequests::SetDraft` defines a `merge_request` 1481field: 1482 1483```ruby 1484field :merge_request, 1485 Types::MergeRequestType, 1486 null: true, 1487 description: "The merge request after mutation." 1488``` 1489 1490This means that the hash returned from `resolve` in this mutation 1491should look like this: 1492 1493```ruby 1494{ 1495 # The merge request modified, this will be wrapped in the type 1496 # defined on the field 1497 merge_request: merge_request, 1498 # An array of strings if the mutation failed after authorization. 1499 # The `errors_on_object` helper collects `errors.full_messages` 1500 errors: errors_on_object(merge_request) 1501} 1502``` 1503 1504### Mounting the mutation 1505 1506To make the mutation available it must be defined on the mutation 1507type that is stored in `graphql/types/mutation_types`. The 1508`mount_mutation` helper method defines a field based on the 1509GraphQL-name of the mutation: 1510 1511```ruby 1512module Types 1513 class MutationType < BaseObject 1514 include Gitlab::Graphql::MountMutation 1515 1516 graphql_name "Mutation" 1517 1518 mount_mutation Mutations::MergeRequests::SetDraft 1519 end 1520end 1521``` 1522 1523Generates a field called `mergeRequestSetDraft` that 1524`Mutations::MergeRequests::SetDraft` to be resolved. 1525 1526### Authorizing resources 1527 1528To authorize resources inside a mutation, we first provide the required 1529 abilities on the mutation like this: 1530 1531```ruby 1532module Mutations 1533 module MergeRequests 1534 class SetDraft < Base 1535 graphql_name 'MergeRequestSetDraft' 1536 1537 authorize :update_merge_request 1538 end 1539 end 1540end 1541``` 1542 1543We can then call `authorize!` in the `resolve` method, passing in the resource we 1544want to validate the abilities for. 1545 1546Alternatively, we can add a `find_object` method that loads the 1547object on the mutation. This would allow you to use the 1548`authorized_find!` helper method. 1549 1550When a user is not allowed to perform the action, or an object is not 1551found, we should raise a 1552`Gitlab::Graphql::Errors::ResourceNotAvailable` error which is 1553correctly rendered to the clients. 1554 1555### Errors in mutations 1556 1557We encourage following the practice of [errors as 1558data](https://graphql-ruby.org/mutations/mutation_errors) for mutations, which 1559distinguishes errors by who they are relevant to, defined by who can deal with 1560them. 1561 1562Key points: 1563 1564- All mutation responses have an `errors` field. This should be populated on 1565 failure, and may be populated on success. 1566- Consider who needs to see the error: the **user** or the **developer**. 1567- Clients should always request the `errors` field when performing mutations. 1568- Errors may be reported to users either at `$root.errors` (top-level error) or at 1569 `$root.data.mutationName.errors` (mutation errors). The location depends on what kind of error 1570 this is, and what information it holds. 1571- Mutation fields [must have `null: true`](https://graphql-ruby.org/mutations/mutation_errors#nullable-mutation-payload-fields) 1572 1573Consider an example mutation `doTheThing` that returns a response with 1574two fields: `errors: [String]`, and `thing: ThingType`. The specific nature of 1575the `thing` itself is irrelevant to these examples, as we are considering the 1576errors. 1577 1578There are three states a mutation response can be in: 1579 1580- [Success](#success) 1581- [Failure (relevant to the user)](#failure-relevant-to-the-user) 1582- [Failure (irrelevant to the user)](#failure-irrelevant-to-the-user) 1583 1584#### Success 1585 1586In the happy path, errors *may* be returned, along with the anticipated payload, but 1587if everything was successful, then `errors` should be an empty array, because 1588there are no problems we need to inform the user of. 1589 1590```javascript 1591{ 1592 data: { 1593 doTheThing: { 1594 errors: [] // if successful, this array will generally be empty. 1595 thing: { .. } 1596 } 1597 } 1598} 1599``` 1600 1601#### Failure (relevant to the user) 1602 1603An error that affects the **user** occurred. We refer to these as _mutation errors_. In 1604this case there is typically no `thing` to return: 1605 1606```javascript 1607{ 1608 data: { 1609 doTheThing: { 1610 errors: ["you cannot touch the thing"], 1611 thing: null 1612 } 1613 } 1614} 1615``` 1616 1617Examples of this include: 1618 1619- Model validation errors: the user may need to change the inputs. 1620- Permission errors: the user needs to know they cannot do this, they may need to request permission or sign in. 1621- Problems with application state that prevent the user's action, for example: merge conflicts, the resource was locked, and so on. 1622 1623Ideally, we should prevent the user from getting this far, but if they do, they 1624need to be told what is wrong, so they understand the reason for the failure and 1625what they can do to achieve their intent, even if that is as simple as retrying the 1626request. 1627 1628It is possible to return *recoverable* errors alongside mutation data. For example, if 1629a user uploads 10 files and 3 of them fail and the rest succeed, the errors for the 1630failures can be made available to the user, alongside the information about 1631the successes. 1632 1633#### Failure (irrelevant to the user) 1634 1635One or more *non-recoverable* errors can be returned at the _top level_. These 1636are things over which the **user** has little to no control, and should mainly 1637be system or programming problems, that a **developer** needs to know about. 1638In this case there is no `data`: 1639 1640```javascript 1641{ 1642 errors: [ 1643 {"message": "argument error: expected an integer, got null"}, 1644 ] 1645} 1646``` 1647 1648This is the result of raising an error during the mutation. In our implementation, 1649the messages of argument errors and validation errors are returned to the client, and all other 1650`StandardError` instances are caught, logged and presented to the client with the message set to `"Internal server error"`. 1651See [`GraphqlController`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/graphql_controller.rb) for details. 1652 1653These represent programming errors, such as: 1654 1655- A GraphQL syntax error, where an `Int` was passed instead of a `String`, or a required argument was not present. 1656- Errors in our schema, such as being unable to provide a value for a non-nullable field. 1657- System errors: for example, a Git storage exception, or database unavailability. 1658 1659The user should not be able to cause such errors in regular usage. This category 1660of errors should be treated as internal, and not shown to the user in specific 1661detail. 1662 1663We need to inform the user when the mutation fails, but we do not need to 1664tell them why, because they cannot have caused it, and nothing they can do 1665fixes it, although we may offer to retry the mutation. 1666 1667#### Categorizing errors 1668 1669When we write mutations, we need to be conscious about which of 1670these two categories an error state falls into (and communicate about this with 1671frontend developers to verify our assumptions). This means distinguishing the 1672needs of the _user_ from the needs of the _client_. 1673 1674> _Never catch an error unless the user needs to know about it._ 1675 1676If the user does need to know about it, communicate with frontend developers 1677to make sure the error information we are passing back is useful. 1678 1679See also the [frontend GraphQL guide](../development/fe_guide/graphql.md#handling-errors). 1680 1681### Aliasing and deprecating mutations 1682 1683The `#mount_aliased_mutation` helper allows us to alias a mutation as 1684another name in `MutationType`. 1685 1686For example, to alias a mutation called `FooMutation` as `BarMutation`: 1687 1688```ruby 1689mount_aliased_mutation 'BarMutation', Mutations::FooMutation 1690``` 1691 1692This allows us to rename a mutation and continue to support the old name, 1693when coupled with the [`deprecated`](#deprecating-fields-arguments-and-enum-values) 1694argument. 1695 1696Example: 1697 1698```ruby 1699mount_aliased_mutation 'UpdateFoo', 1700 Mutations::Foo::Update, 1701 deprecated: { reason: 'Use fooUpdate', milestone: '13.2' } 1702``` 1703 1704Deprecated mutations should be added to `Types::DeprecatedMutations` and 1705tested for in the unit test of `Types::MutationType`. The merge request 1706[!34798](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34798) 1707can be referred to as an example of this, including the method of testing 1708deprecated aliased mutations. 1709 1710#### Deprecating EE mutations 1711 1712EE mutations should follow the same process. For an example of the merge request 1713process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42588). 1714 1715## Subscriptions 1716 1717We use subscriptions to push updates to clients. We use the [Action Cable implementation](https://graphql-ruby.org/subscriptions/action_cable_implementation) 1718to deliver the messages over websockets. 1719 1720When a client subscribes to a subscription, we store their query in-memory within Puma workers. Then when the subscription is triggered, 1721the Puma workers execute the stored GraphQL queries and push the results to the clients. 1722 1723NOTE: 1724We cannot test subscriptions using GraphiQL, because they require an Action Cable client, which GraphiQL does not support at the moment. 1725 1726### Building subscriptions 1727 1728All fields under `Types::SubscriptionType` are subscriptions that clients can subscribe to. These fields require a subscription class, 1729which is a descendant of `Subscriptions::BaseSubscription` and is stored under `app/graphql/subscriptions`. 1730 1731The arguments required to subscribe and the fields that are returned are defined in the subscription class. Multiple fields can share 1732the same subscription class if they have the same arguments and return the same fields. 1733 1734This class runs during the initial subscription request and subsequent updates. You can read more about this in the 1735[GraphQL Ruby guides](https://graphql-ruby.org/subscriptions/subscription_classes). 1736 1737### Authorization 1738 1739You should implement the `#authorized?` method of the subscription class so that the initial subscription and subsequent updates are authorized. 1740 1741When a user is not authorized, you should call the `unauthorized!` helper so that execution is halted and the user is unsubscribed. Returning `false` 1742results in redaction of the response but we leak information that some updates are happening. This is due to a 1743[bug in the GraphQL gem](https://github.com/rmosolgo/graphql-ruby/issues/3390). 1744 1745### Triggering subscriptions 1746 1747Define a method under the `GraphqlTriggers` module to trigger a subscription. Do not call `GitlabSchema.subscriptions.trigger` directly in application 1748code so that we have a single source of truth and we do not trigger a subscription with different arguments and objects. 1749 1750## Pagination implementation 1751 1752To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). 1753 1754## Validating arguments 1755 1756For validations of single arguments, use the 1757[`prepare` option](https://github.com/rmosolgo/graphql-ruby/blob/master/guides/fields/arguments.md) 1758as normal. 1759 1760Sometimes a mutation or resolver may accept a number of optional 1761arguments, but we still want to validate that at least one of the optional 1762arguments is provided. In this situation, consider using the `#ready?` 1763method in your mutation or resolver to provide the validation. The 1764`#ready?` method is called before any work is done in the 1765`#resolve` method. 1766 1767Example: 1768 1769```ruby 1770def ready?(**args) 1771 if args.values_at(:body, :position).compact.blank? 1772 raise Gitlab::Graphql::Errors::ArgumentError, 1773 'body or position arguments are required' 1774 end 1775 1776 # Always remember to call `#super` 1777 super 1778end 1779``` 1780 1781In the future this may be able to be done using `InputUnions` if 1782[this RFC](https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md) 1783is merged. 1784 1785## GitLab custom scalars 1786 1787### `Types::TimeType` 1788 1789[`Types::TimeType`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app%2Fgraphql%2Ftypes%2Ftime_type.rb) 1790must be used as the type for all fields and arguments that deal with Ruby 1791`Time` and `DateTime` objects. 1792 1793The type is 1794[a custom scalar](https://github.com/rmosolgo/graphql-ruby/blob/master/guides/type_definitions/scalars.md#custom-scalars) 1795that: 1796 1797- Converts Ruby's `Time` and `DateTime` objects into standardized 1798 ISO-8601 formatted strings, when used as the type for our GraphQL fields. 1799- Converts ISO-8601 formatted time strings into Ruby `Time` objects, 1800 when used as the type for our GraphQL arguments. 1801 1802This allows our GraphQL API to have a standardized way that it presents time 1803and handles time inputs. 1804 1805Example: 1806 1807```ruby 1808field :created_at, Types::TimeType, null: true, description: 'Timestamp of when the issue was created.' 1809``` 1810 1811## Testing 1812 1813### Writing unit tests 1814 1815Before creating unit tests, review the following examples: 1816 1817- [`spec/graphql/resolvers/users_resolver_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/resolvers/users_resolver_spec.rb) 1818- [`spec/graphql/mutations/issues/create_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/mutations/issues/create_spec.rb) 1819 1820It's faster to test as much of the logic from your GraphQL queries and mutations 1821with unit tests, which are stored in `spec/graphql`. 1822 1823Use unit tests to verify that: 1824 1825- Types have the expected fields. 1826- Resolvers and mutations apply authorizations and return expected data. 1827- Edge cases are handled correctly. 1828 1829### Writing integration tests 1830 1831Integration tests check the full stack for a GraphQL query or mutation and are stored in 1832`spec/requests/api/graphql`. 1833 1834For speed, you should test most logic in unit tests instead of integration tests. 1835However, integration tests that check if data is returned verify the following 1836additional items: 1837 1838- The mutation is actually queryable in the schema (was mounted in `MutationType`). 1839- The data returned by a resolver or mutation correctly matches the 1840 [return types](https://graphql-ruby.org/fields/introduction.html#field-return-type) of 1841 the fields and resolves without errors. 1842 1843Integration tests can also verify the following items, because they invoke the 1844full stack: 1845 1846- An argument or scalar's [`prepare`](#validating-arguments) applies correctly. 1847- Logic in a resolver or mutation's [`#ready?` method](#correct-use-of-resolverready) applies correctly. 1848- An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly. 1849- Objects resolve successfully, and there are no N+1 issues. 1850 1851When adding a query, you can use the `a working graphql query` shared example to test if the query 1852renders valid results. 1853 1854You can construct a query including all available fields using the `GraphqlHelpers#all_graphql_fields_for` 1855helper. This makes it easy to add a test rendering all possible fields for a query. 1856 1857If you're adding a field to a query that supports pagination and sorting, 1858visit [Testing](graphql_guide/pagination.md#testing) for details. 1859 1860To test GraphQL mutation requests, `GraphqlHelpers` provides two 1861helpers: `graphql_mutation` which takes the name of the mutation, and 1862a hash with the input for the mutation. This returns a struct with 1863a mutation query, and prepared variables. 1864 1865You can then pass this struct to the `post_graphql_mutation` helper, 1866that posts the request with the correct parameters, like a GraphQL 1867client would do. 1868 1869To access the response of a mutation, you can use the `graphql_mutation_response` 1870helper. 1871 1872Using these helpers, you can build specs like this: 1873 1874```ruby 1875let(:mutation) do 1876 graphql_mutation( 1877 :merge_request_set_wip, 1878 project_path: 'gitlab-org/gitlab-foss', 1879 iid: '1', 1880 wip: true 1881 ) 1882end 1883 1884it 'returns a successful response' do 1885 post_graphql_mutation(mutation, current_user: user) 1886 1887 expect(response).to have_gitlab_http_status(:success) 1888 expect(graphql_mutation_response(:merge_request_set_wip)['errors']).to be_empty 1889end 1890``` 1891 1892### Testing tips and tricks 1893 1894- Avoid false positives: 1895 1896 Authenticating a user with the `current_user:` argument for `post_graphql` 1897 generates more queries on the first request than on subsequent requests on that 1898 same user. If you are testing for N+1 queries using 1899 [QueryRecorder](query_recorder.md), use a **different** user for each request. 1900 1901 The below example shows how a test for avoiding N+1 queries should look: 1902 1903 ```ruby 1904 RSpec.describe 'Query.project(fullPath).pipelines' do 1905 include GraphqlHelpers 1906 1907 let(:project) { create(:project) } 1908 1909 let(:query) do 1910 %( 1911 { 1912 project(fullPath: "#{project.full_path}") { 1913 pipelines { 1914 nodes { 1915 id 1916 } 1917 } 1918 } 1919 } 1920 ) 1921 end 1922 1923 it 'avoids N+1 queries' do 1924 first_user = create(:user) 1925 second_user = create(:user) 1926 create(:ci_pipeline, project: project) 1927 1928 control_count = ActiveRecord::QueryRecorder.new do 1929 post_graphql(query, current_user: first_user) 1930 end 1931 1932 create(:ci_pipeline, project: project) 1933 1934 expect do 1935 post_graphql(query, current_user: second_user) # use a different user to avoid a false positive from authentication queries 1936 end.not_to exceed_query_limit(control_count) 1937 end 1938 end 1939 ``` 1940 1941- Mimic the folder structure of `app/graphql/types`: 1942 1943 For example, tests for fields on `Types::Ci::PipelineType` 1944 in `app/graphql/types/ci/pipeline_type.rb` should be stored in 1945 `spec/requests/api/graphql/ci/pipeline_spec.rb` regardless of the query being 1946 used to fetch the pipeline data. 1947 1948## Notes about Query flow and GraphQL infrastructure 1949 1950The GitLab GraphQL infrastructure can be found in `lib/gitlab/graphql`. 1951 1952[Instrumentation](https://graphql-ruby.org/queries/instrumentation.html) is functionality 1953that wraps around a query being executed. It is implemented as a module that uses the `Instrumentation` class. 1954 1955Example: `Present` 1956 1957```ruby 1958module Gitlab 1959 module Graphql 1960 module Present 1961 #... some code above... 1962 1963 def self.use(schema_definition) 1964 schema_definition.instrument(:field, ::Gitlab::Graphql::Present::Instrumentation.new) 1965 end 1966 end 1967 end 1968end 1969``` 1970 1971A [Query Analyzer](https://graphql-ruby.org/queries/ast_analysis.html#analyzer-api) contains a series 1972of callbacks to validate queries before they are executed. Each field can pass through 1973the analyzer, and the final value is also available to you. 1974 1975[Multiplex queries](https://graphql-ruby.org/queries/multiplex.html) enable 1976multiple queries to be sent in a single request. This reduces the number of requests sent to the server. 1977(there are custom Multiplex Query Analyzers and Multiplex Instrumentation provided by GraphQL Ruby). 1978 1979### Query limits 1980 1981Queries and mutations are limited by depth, complexity, and recursion 1982to protect server resources from overly ambitious or malicious queries. 1983These values can be set as defaults and overridden in specific queries as needed. 1984The complexity values can be set per object as well, and the final query complexity is 1985evaluated based on how many objects are being returned. This is useful 1986for objects that are expensive (such as requiring Gitaly calls). 1987 1988For example, a conditional complexity method in a resolver: 1989 1990```ruby 1991def self.resolver_complexity(args, child_complexity:) 1992 complexity = super 1993 complexity += 2 if args[:labelName] 1994 1995 complexity 1996end 1997``` 1998 1999More about complexity: 2000[GraphQL Ruby documentation](https://graphql-ruby.org/queries/complexity_and_depth.html). 2001 2002## Documentation and schema 2003 2004Our schema is located at `app/graphql/gitlab_schema.rb`. 2005See the [schema reference](../api/graphql/reference/index.md) for details. 2006 2007This generated GraphQL documentation needs to be updated when the schema changes. 2008For information on generating GraphQL documentation and schema files, see 2009[updating the schema documentation](rake_tasks.md#update-graphql-documentation-and-schema-definitions). 2010 2011To help our readers, you should also add a new page to our [GraphQL API](../api/graphql/index.md) documentation. 2012For guidance, see the [GraphQL API](documentation/graphql_styleguide.md) page. 2013 2014## Include a changelog entry 2015 2016All client-facing changes **must** include a [changelog entry](changelog.md). 2017 2018## Laziness 2019 2020One important technique unique to GraphQL for managing performance is 2021using **lazy** values. Lazy values represent the promise of a result, 2022allowing their action to be run later, which enables batching of queries in 2023different parts of the query tree. The main example of lazy values in our code is 2024the [GraphQL BatchLoader](graphql_guide/batchloader.md). 2025 2026To manage lazy values directly, read `Gitlab::Graphql::Lazy`, and in 2027particular `Gitlab::Graphql::Laziness`. This contains `#force` and 2028`#delay`, which help implement the basic operations of creation and 2029elimination of laziness, where needed. 2030 2031For dealing with lazy values without forcing them, use 2032`Gitlab::Graphql::Lazy.with_value`. 2033 2034## Monitoring GraphQL 2035 2036See the [Monitoring GraphQL](graphql_guide/monitoring.md) guide for tips on how to inspect logs of GraphQL requests and monitor the performance of your GraphQL queries. 2037