GraphQL은 API를 위한 쿼리 언어입니다. 필요한 정확한 데이터만 요청하여 필요한 요청 수를 줄일 수 있습니다.

GraphQL 데이터는 타입으로 구성되어 있으므로 클라이언트가 클라이언트 측 GraphQL 라이브러리를 사용하여 API를 소비하고 수동 파싱을 방지할 수 있습니다.

GraphQL API는 버전이 없습니다.

시작하기#

GitLab GraphQL API를 처음 사용하는 경우 GitLab GraphQL API 시작하기를 참조하세요.

GraphQL API 레퍼런스에서 사용 가능한 리소스를 확인할 수 있습니다.

GitLab GraphQL API 엔드포인트는 /api/graphql에 있습니다.

대화형 GraphQL 탐색기#

다음 중 하나에서 대화형 GraphQL 탐색기를 사용하여 GraphQL API를 탐색하세요:

• GitLab.com에서.
• https://<your-gitlab-site.com>/-/graphql-explorer의 GitLab Self-Managed에서.

자세한 내용은 GraphiQL을 참조하세요.

GraphQL 예제 보기#

GitLab.com의 공개 프로젝트에서 데이터를 가져오는 샘플 쿼리로 작업할 수 있습니다:

• 감사 보고서 생성
• 이슈 보드 식별
• 사용자 쿼리
• 사용자 정의 이모지 사용

시작하기 페이지에는 GraphQL 쿼리를 사용자 지정하는 다양한 방법이 포함되어 있습니다.

인증#

일부 쿼리는 인증 없이도 액세스할 수 있지만, 다른 쿼리는 인증이 필요합니다. Mutation은 항상 인증이 필요합니다.

다음 중 하나를 사용하여 인증할 수 있습니다:

• 토큰
• 세션 쿠키

인증 정보가 유효하지 않으면 GitLab은 상태 코드 401과 함께 오류 메시지를 반환합니다:

{"errors":[{"message":"Invalid token"}]}

토큰 인증#

다음 토큰 중 하나를 사용하여 GraphQL API로 인증하세요:

• OAuth 2.0 토큰
• 개인 접근 토큰
• 프로젝트 접근 토큰
• 그룹 접근 토큰

요청 헤더 또는 매개변수로 전달하여 토큰으로 인증합니다.

토큰은 올바른 범위가 필요합니다.

헤더 인증#

Authorization: Bearer <token> 요청 헤더를 사용한 토큰 인증 예시:

curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

매개변수 인증#

access_token 매개변수에서 OAuth 2.0 토큰 사용 예시:

curl --request POST \
  --url "https://gitlab.com/api/graphql?access_token=<oauth_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

private_token 매개변수를 사용하여 개인, 프로젝트 또는 그룹 접근 토큰을 전달할 수 있습니다:

curl --request POST \
  --url "https://gitlab.com/api/graphql?private_token=<access_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

토큰 범위#

토큰은 GraphQL API에 액세스하기 위한 올바른 범위가 있어야 합니다:

세션 쿠키 인증#

기본 GitLab 애플리케이션에 로그인하면 _gitlab_session 세션 쿠키가 설정됩니다.

대화형 GraphQL 탐색기와 GitLab 자체의 웹 프론트엔드는 이 인증 방법을 사용합니다.

인가#

인증 후 GraphQL API는 요청된 각 리소스에 대한 권한을 확인합니다. API가 인가 실패를 보고하는 방식은 작업 유형에 따라 다릅니다.

쿼리 필드#

쿼리 필드는 리소스에 액세스할 권한이 없을 때 null을 반환합니다. 응답에는 오류 메시지가 포함되지 않습니다.

이 동작은 의도적입니다. API는 권한이 없는 리소스와 존재하지 않는 리소스에 동일한 null 응답을 반환하므로, 클라이언트가 서버에 어떤 리소스가 존재하는지 열거할 수 없습니다.

예를 들어 보유하지 않은 역할 또는 애드온이 필요한 필드를 쿼리하면 errors 배열에 항목이 표시되지 않습니다:

{
  "data": {
    "group": {
      "fieldRequiringPermission": null
    }
  }
}

예기치 않은 null을 받으면 다음을 확인하세요:

• 토큰에 필요한 범위가 있는지.
• 역할이 GraphQL API 레퍼런스에 문서화된 최소 접근 수준을 충족하는지.
• 인스턴스에 필요한 구독 티어, 기능 또는 애드온이 활성화되어 있는지.

Mutation#

Mutation은 인가에 실패하면 오류 메시지를 반환합니다. 오류는 최상위 errors 배열에 null 데이터 필드와 함께 표시됩니다:

{
  "data": {
    "mutationName": null
  },
  "errors": [
    {
      "message": "The resource that you are attempting to access does not exist or you don't have permission to perform this action",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["mutationName"]
    }
  ]
}

오류 메시지는 리소스 유형에 따라 다를 수 있습니다.

객체 식별자#

GitLab GraphQL API는 혼합된 식별자를 사용합니다.

전역 ID, 전체 경로, 내부 ID(IID)는 모두 GitLab GraphQL API에서 인수로 사용되지만, 스키마의 특정 부분은 이 모두를 동시에 허용하지 않는 경우가 많습니다.

GitLab GraphQL API는 역사적으로 일관성이 없었지만, 일반적으로 다음을 기대할 수 있습니다:

• 객체가 프로젝트, 그룹 또는 네임스페이스인 경우 객체의 전체 경로를 사용합니다.
• 객체에 IID가 있는 경우 전체 경로와 IID의 조합을 사용합니다.
• 다른 객체의 경우 전역 ID를 사용합니다.

예를 들어 전체 경로 "gitlab-org/gitlab"로 프로젝트 찾기:

{
  project(fullPath: "gitlab-org/gitlab") {
    id
    fullPath
  }
}

또 다른 예로, 프로젝트 전체 경로 "gitlab-org/gitlab"와 이슈 IID "1"로 이슈 잠금:

mutation {
  issueSetLocked(input: { projectPath: "gitlab-org/gitlab", iid: "1", locked: true }) {
    issue {
      id
      iid
    }
  }
}

전역 ID로 CI 러너 찾기 예시:

{
  runner(id: "gid://gitlab/Ci::Runner/1") {
    id
  }
}

GitLab GraphQL API는 전체 경로 및 IID 필드와 인수의 타이핑이 일관성이 없었지만, 일반적으로:

• 전체 경로 필드와 인수는 GraphQL ID 타입입니다.
• IID 필드와 인수는 GraphQL String 타입입니다.

전역 ID#

GitLab GraphQL API에서 id라는 필드나 인수는 거의 항상 전역 ID이며 데이터베이스 기본 키 ID가 아닙니다. GitLab GraphQL API의 전역 ID는 "gid://gitlab/"로 시작합니다. 예: "gid://gitlab/Issue/123".

전역 ID는 일부 클라이언트 측 라이브러리에서 캐싱 및 가져오기를 위해 사용하는 규칙입니다.

GitLab 전역 ID는 변경될 수 있습니다. 변경된 경우 이전 전역 ID를 인수로 사용하는 것은 더 이상 사용되지 않으며 폐지 및 주요 변경 프로세스에 따라 지원됩니다. 캐시된 전역 ID가 GitLab GraphQL 폐지 주기를 넘어 유효할 것으로 기대해서는 안 됩니다.

사용 가능한 최상위 쿼리#

모든 쿼리의 최상위 진입점은 GraphQL 레퍼런스의 Query 타입에 정의되어 있습니다.

멀티플렉스 쿼리#

GitLab은 쿼리를 단일 요청으로 일괄 처리하는 것을 지원합니다. 자세한 내용은 Multiplex를 참조하세요.

주요 변경사항#

GitLab GraphQL API는 버전이 없으며 API에 대한 변경은 주로 하위 호환성을 유지합니다.

그러나 GitLab은 때때로 하위 호환성이 없는 방식으로 GraphQL API를 변경합니다. 이러한 변경은 주요 변경사항으로 간주되며, 필드, 인수 또는 스키마의 다른 부분을 제거하거나 이름을 바꾸는 것을 포함할 수 있습니다. 주요 변경사항을 만들 때 GitLab은 폐지 및 제거 프로세스를 따릅니다.

주요 변경사항이 통합에 영향을 미치지 않으려면:

• 폐지 및 제거 프로세스에 익숙해지세요.
• 자주 향후 주요 변경 스키마에 대해 API 호출을 검증하세요.

GitLab Self-Managed의 경우 EE 인스턴스를 CE로 되돌리면 주요 변경사항이 발생합니다.

주요 변경사항 면제#

GraphQL API 레퍼런스에서 실험으로 표시된 스키마 항목은 폐지 프로세스에서 면제됩니다. 이러한 항목은 공지 없이 언제든지 제거되거나 변경될 수 있습니다.

기능 플래그 뒤에 있고 기본적으로 비활성화된 필드는 폐지 및 제거 프로세스를 따르지 않습니다. 이러한 필드는 공지 없이 언제든지 제거될 수 있습니다.

향후 주요 변경 스키마에 대한 검증#

히스토리

• GitLab 15.6에서 도입되었습니다.

모든 폐지된 항목이 이미 제거된 것처럼 GraphQL API에 대해 호출할 수 있습니다. 이렇게 하면 항목이 스키마에서 실제로 제거되기 전에 주요 변경 릴리스 전에 API 호출을 검증할 수 있습니다.

이러한 호출을 만들려면 GraphQL API 엔드포인트에 remove_deprecated=true 쿼리 매개변수를 추가합니다. 예를 들어 GitLab.com의 GraphQL에 대해 https://gitlab.com/api/graphql?remove_deprecated=true.

폐지 및 제거 프로세스#

GitLab GraphQL API에서 제거될 예정인 스키마 부분은 먼저 폐지되지만 최소 6개 릴리스 동안은 사용 가능합니다. 그런 다음 다음 XX.0 주요 릴리스에서 완전히 제거됩니다.

항목은 다음에서 폐지로 표시됩니다:

• 스키마.
• GraphQL API 레퍼런스.
• 릴리스 포스트에서 링크된 폐지 기능 제거 일정.
• GraphQL API의 내성 쿼리.

폐지 메시지는 해당하는 경우 폐지된 스키마 항목의 대안을 제공합니다.

주요 변경사항을 겪지 않으려면 가능한 한 빨리 GraphQL API 호출에서 폐지된 스키마를 제거해야 합니다. 폐지된 스키마 항목 없이 스키마에 대해 API 호출을 검증해야 합니다.

폐지 예시#

다음 필드는 서로 다른 마이너 릴리스에서 폐지되었지만 둘 다 GitLab 17.0에서 제거됩니다:

제거된 항목 목록#

이전 릴리스에서 제거된 항목 목록을 확인하세요.

제한사항#

GitLab GraphQL API에는 다음과 같은 제한사항이 적용됩니다.

최대 쿼리 복잡성#

GitLab GraphQL API는 쿼리의 복잡성을 점수로 매깁니다. 일반적으로 더 큰 쿼리일수록 복잡성 점수가 높습니다. 이 제한은 전반적인 성능에 부정적인 영향을 미칠 수 있는 쿼리 수행으로부터 API를 보호하기 위한 것입니다.

쿼리의 복잡성 점수와 요청 제한을 쿼리할 수 있습니다.

쿼리가 복잡성 제한을 초과하면 오류 메시지 응답이 반환됩니다.

일반적으로 쿼리의 각 필드는 복잡성 점수에 1을 추가하지만, 특정 필드의 경우 더 높거나 낮을 수 있습니다. 특정 인수를 추가하면 쿼리의 복잡성이 증가할 수도 있습니다.

데이터 제한#

blob 요청은 다음으로 제한됩니다:

• 크기에 관계없이 단일 blob.
• 총 크기 20MB 이하의 여러 blob.

20MB보다 큰 blob은 개별적으로 요청해야 합니다. 이 제한은 blob 데이터가 포함된 필드를 요청할 때만 적용됩니다.

데이터 제한 내에 있으려면 요청의 경로 수를 제한해야 할 수 있습니다. 데이터 필드를 제외하고 size 필드에 대한 요청을 만드세요:

{
  project(fullPath: "gitlab-org/gitlab") {
    repository {
      blobs(paths: ["big_file.rb", "small_file.rb", "huge_file.rb", ..., etc.], ref: "master") {
        nodes {
          path
          size
        }
      }
    }
  }
}

응답을 사용하여 총 크기를 계산하고 후속 요청이 20MB 데이터 제한을 초과하지 않는지 확인하세요.

스팸으로 감지된 mutation 해결#

GraphQL mutation은 스팸으로 감지될 수 있습니다. mutation이 스팸으로 감지되고:

• CAPTCHA 서비스가 구성되어 있지 않은 경우 GraphQL 최상위 오류가 발생합니다. 예:

  {
    "errors": [
      {
        "message": "Request denied. Spam detected",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "spam": true
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null
      }
    }
  }
  

• CAPTCHA 서비스가 구성된 경우 다음과 함께 응답을 받습니다:

  • needsCaptchaResponse가 true로 설정됨.
  • spamLogId 및 captchaSiteKey 필드가 설정됨.

  예:

  {
    "errors": [
      {
        "message": "Request denied. Solve CAPTCHA challenge and retry",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "needsCaptchaResponse": true,
          "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
          "spamLogId": 67
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null,
      }
    }
  }
  

• captchaSiteKey를 사용하여 적절한 CAPTCHA API를 사용하여 CAPTCHA 응답 값을 얻습니다. Google reCAPTCHA v2만 지원됩니다.

• X-GitLab-Captcha-Response 및 X-GitLab-Spam-Log-Id 헤더를 설정하여 요청을 재제출합니다.

export CAPTCHA_RESPONSE=""
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --request POST \
  --header "Authorization: Bearer $PRIVATE_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" \
  --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" \
  --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"