228 lines
7 KiB
Text
228 lines
7 KiB
Text
-# haml-lint:disable UnnecessaryStringOutput
|
|
|
|
= auto_generated_comment
|
|
|
|
:plain
|
|
# GraphQL API Resources
|
|
|
|
This documentation is self-generated based on GitLab current GraphQL schema.
|
|
|
|
The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
|
|
|
|
Each table below documents a GraphQL type. Types match loosely to models, but not all
|
|
fields and methods on a model are available via GraphQL.
|
|
|
|
WARNING:
|
|
Fields that are deprecated are marked with **{warning-solid}**.
|
|
Items (fields, enums, etc) that have been removed according to our [deprecation process](../index.md#deprecation-and-removal-process) can be found
|
|
in [Removed Items](../removed_items.md).
|
|
|
|
<!-- vale off -->
|
|
<!-- Vale linting disabled after this line. -->
|
|
<!-- See https://docs.gitlab.com/ee/development/documentation/testing.html#disable-vale-tests -->
|
|
|
|
<!-- markdownlint-disable MD044 -->
|
|
<!-- MD044/proper-names test disabled after this line to make page compatible with markdownlint-cli 0.29.0. -->
|
|
<!-- See https://docs.gitlab.com/ee/development/documentation/testing.html#disable-markdownlint-tests -->
|
|
\
|
|
|
|
:plain
|
|
## `Query` type
|
|
|
|
The `Query` type contains the API's top-level entry points for all executable queries.
|
|
\
|
|
|
|
- fields_of('Query').each do |field|
|
|
= render_full_field(field, heading_level: 3, owner: 'Query')
|
|
\
|
|
|
|
:plain
|
|
## `Mutation` type
|
|
|
|
The `Mutation` type contains all the mutations you can execute.
|
|
|
|
All mutations receive their arguments in a single input object named `input`, and all mutations
|
|
support at least a return field `errors` containing a list of error messages.
|
|
|
|
All input objects may have a `clientMutationId: String` field, identifying the mutation.
|
|
|
|
For example:
|
|
|
|
```graphql
|
|
mutation($id: NoteableID!, $body: String!) {
|
|
createNote(input: { noteableId: $id, body: $body }) {
|
|
errors
|
|
}
|
|
}
|
|
```
|
|
\
|
|
|
|
- mutations.each do |field|
|
|
= render_full_field(field, heading_level: 3, owner: 'Mutation')
|
|
\
|
|
|
|
:plain
|
|
## Connections
|
|
|
|
Some types in our schema are `Connection` types - they represent a paginated
|
|
collection of edges between two nodes in the graph. These follow the
|
|
[Relay cursor connections specification](https://relay.dev/graphql/connections.htm).
|
|
|
|
### Pagination arguments {#connection-pagination-arguments}
|
|
|
|
All connection fields support the following pagination arguments:
|
|
|
|
| Name | Type | Description |
|
|
|------|------|-------------|
|
|
| `after` | [`String`](#string) | Returns the elements in the list that come after the specified cursor. |
|
|
| `before` | [`String`](#string) | Returns the elements in the list that come before the specified cursor. |
|
|
| `first` | [`Int`](#int) | Returns the first _n_ elements from the list. |
|
|
| `last` | [`Int`](#int) | Returns the last _n_ elements from the list. |
|
|
|
|
Since these arguments are common to all connection fields, they are not repeated for each connection.
|
|
|
|
### Connection fields
|
|
|
|
All connections have at least the following fields:
|
|
|
|
| Name | Type | Description |
|
|
|------|------|-------------|
|
|
| `pageInfo` | [`PageInfo!`](#pageinfo) | Pagination information. |
|
|
| `edges` | `[edge!]` | The edges. |
|
|
| `nodes` | `[item!]` | The items in the current page. |
|
|
|
|
The precise type of `Edge` and `Item` depends on the kind of connection. A
|
|
[`ProjectConnection`](#projectconnection) will have nodes that have the type
|
|
[`[Project!]`](#project), and edges that have the type [`ProjectEdge`](#projectedge).
|
|
|
|
### Connection types
|
|
|
|
Some of the types in the schema exist solely to model connections. Each connection
|
|
has a distinct, named type, with a distinct named edge type. These are listed separately
|
|
below.
|
|
\
|
|
|
|
- connection_object_types.each do |type|
|
|
= render_name_and_description(type, level: 4)
|
|
\
|
|
= render_object_fields(type[:fields], owner: type, level_bump: 1)
|
|
\
|
|
|
|
:plain
|
|
## Object types
|
|
|
|
Object types represent the resources that the GitLab GraphQL API can return.
|
|
They contain _fields_. Each field has its own type, which will either be one of the
|
|
basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types)
|
|
(e.g.: `String` or `Boolean`) or other object types. Fields may have arguments.
|
|
Fields with arguments are exactly like top-level queries, and are listed beneath
|
|
the table of fields for each object type.
|
|
|
|
For more information, see
|
|
[Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields)
|
|
on `graphql.org`.
|
|
\
|
|
|
|
- object_types.each do |type|
|
|
= render_name_and_description(type)
|
|
\
|
|
= render_object_fields(type[:fields], owner: type)
|
|
\
|
|
|
|
:plain
|
|
## Enumeration types
|
|
|
|
Also called _Enums_, enumeration types are a special kind of scalar that
|
|
is restricted to a particular set of allowed values.
|
|
|
|
For more information, see
|
|
[Enumeration Types](https://graphql.org/learn/schema/#enumeration-types)
|
|
on `graphql.org`.
|
|
\
|
|
|
|
- enums.each do |enum|
|
|
= render_name_and_description(enum)
|
|
\
|
|
~ "| Value | Description |"
|
|
~ "| ----- | ----------- |"
|
|
- enum[:values].each do |value|
|
|
= render_enum_value(enum, value)
|
|
\
|
|
|
|
:plain
|
|
## Scalar types
|
|
|
|
Scalar values are atomic values, and do not have fields of their own.
|
|
Basic scalars include strings, boolean values, and numbers. This schema also
|
|
defines various custom scalar values, such as types for times and dates.
|
|
|
|
This schema includes custom scalar types for identifiers, with a specific type for
|
|
each kind of object.
|
|
|
|
For more information, read about [Scalar Types](https://graphql.org/learn/schema/#scalar-types) on `graphql.org`.
|
|
\
|
|
|
|
- graphql_scalar_types.each do |type|
|
|
= render_name_and_description(type)
|
|
\
|
|
|
|
:plain
|
|
## Abstract types
|
|
|
|
Abstract types (unions and interfaces) are ways the schema can represent
|
|
values that may be one of several concrete types.
|
|
|
|
- A [`Union`](https://graphql.org/learn/schema/#union-types) is a set of possible types.
|
|
The types might not have any fields in common.
|
|
- An [`Interface`](https://graphql.org/learn/schema/#interfaces) is a defined set of fields.
|
|
Types may `implement` an interface, which
|
|
guarantees that they have all the fields in the set. A type may implement more than
|
|
one interface.
|
|
|
|
See the [GraphQL documentation](https://graphql.org/learn/) for more information on using
|
|
abstract types.
|
|
\
|
|
|
|
:plain
|
|
### Unions
|
|
\
|
|
|
|
- graphql_union_types.each do |type|
|
|
= render_name_and_description(type, level: 4)
|
|
\
|
|
One of:
|
|
\
|
|
- type[:possible_types].each do |member|
|
|
= render_union_member(member)
|
|
\
|
|
|
|
:plain
|
|
### Interfaces
|
|
\
|
|
|
|
- interfaces.each do |type|
|
|
= render_name_and_description(type, level: 4)
|
|
\
|
|
Implementations:
|
|
\
|
|
- type[:implemented_by].each do |type_name|
|
|
~ "- [`#{type_name}`](##{type_name.downcase})"
|
|
\
|
|
= render_object_fields(type[:fields], owner: type, level_bump: 1)
|
|
\
|
|
|
|
:plain
|
|
## Input types
|
|
|
|
Types that may be used as arguments (all scalar types may also
|
|
be used as arguments).
|
|
|
|
Only general use input types are listed here. For mutation input types,
|
|
see the associated mutation type above.
|
|
\
|
|
|
|
- input_types.each do |type|
|
|
= render_name_and_description(type)
|
|
\
|
|
= render_argument_table(3, type[:input_fields], type[:name])
|
|
\
|