Load @octokit/graphql
directly from cdn.pika.dev
<script type="module"> import { endpoint } from "https://cdn.pika.dev/@octokit/graphql"; </script>
Install with npm install @octokit/graphql
const { graphql } = require("@octokit/graphql"); // or: import { graphql } from "@octokit/graphql";
const { repository } = await graphql( ` { repository(owner: "octokit", name: "graphql.js") { issues(last: 3) { edges { node { title } } } } } `, { headers: { authorization: `token secret123` } } );
The simplest way to authenticate a request is to set the Authorization
header, e.g. to a personal access token.
const graphqlWithAuth = graphql.defaults({ headers: { authorization: `token secret123` } }); const { repository } = await graphqlWithAuth(` { repository(owner: "octokit", name: "graphql.js") { issues(last: 3) { edges { node { title } } } } } `);
For more complex authentication strategies such as GitHub Apps or Basic, we recommend the according authentication library exported by @octokit/auth
.
const { createAppAuth } = require("@octokit/auth-app"); const auth = createAppAuth({ id: process.env.APP_ID, privateKey: process.env.PRIVATE_KEY, installationId: 123 }); const graphqlWithAuth = graphql.defaults({ request: { hook: auth.hook } }); const { repository } = await graphqlWithAuth( `{ repository(owner: "octokit", name: "graphql.js") { issues(last: 3) { edges { node { title } } } } }` );
⚠️ Do not use template literals in the query strings as they make your code vulnerable to query injection attacks (see #2). Use variables instead:
const { lastIssues } = await graphql(`query lastIssues($owner: String!, $repo: String!, $num: Int = 3) { repository(owner:$owner, name:$repo) { issues(last:$num) { edges { node { title } } } } }`, { owner: 'octokit', repo: 'graphql.js' headers: { authorization: `token secret123` } } })
const { graphql } = require('@octokit/graphql') const { lastIssues } = await graphql({ query: `query lastIssues($owner: String!, $repo: String!, $num: Int = 3) { repository(owner:$owner, name:$repo) { issues(last:$num) { edges { node { title } } } } }`, owner: 'octokit', repo: 'graphql.js' headers: { authorization: `token secret123` } })
let { graphql } = require("@octokit/graphql"); graphql = graphql.defaults({ baseUrl: "https://github-enterprise.acme-inc.com/api", headers: { authorization: `token secret123` } }); const { repository } = await graphql(` { repository(owner: "acme-project", name: "acme-repo") { issues(last: 3) { edges { node { title } } } } } `);
@octokit/request
instanceconst { request } = require("@octokit/request"); const { withCustomRequest } = require("@octokit/graphql"); let requestCounter = 0 const myRequest = request.defaults({ headers: { authentication: 'token secret123' }, request: { hook(request, options) { requestCounter++ return request(options) } } }) const myGraphql = withCustomRequest(myRequest) await request('/') await myGraphql(` { repository(owner: "acme-project", name: "acme-repo") { issues(last: 3) { edges { node { title } } } } } `); // requestCounter is now 2
In case of a GraphQL error, error.message
is set to the first error from the response’s errors
array. All errors can be accessed at error.errors
. error.request
has the request options such as query, variables and headers set for easier debugging.
let { graphql } = require("@octokit/graphql"); graphqlt = graphql.defaults({ headers: { authorization: `token secret123` } }); const query = `{ viewer { bioHtml } }`; try { const result = await graphql(query); } catch (error) { // server responds with // { // "data": null, // "errors": [{ // "message": "Field 'bioHtml' doesn't exist on type 'User'", // "locations": [{ // "line": 3, // "column": 5 // }] // }] // } console.log("Request failed:", error.request); // { query, variables: {}, headers: { authorization: 'token secret123' } } console.log(error.message); // Field 'bioHtml' doesn't exist on type 'User' }
A GraphQL query may respond with partial data accompanied by errors. In this case we will throw an error but the partial data will still be accessible through error.data
let { graphql } = require("@octokit/graphql"); graphql = graphql.defaults({ headers: { authorization: `token secret123` } }); const query = `{ repository(name: "probot", owner: "probot") { name ref(qualifiedName: "master") { target { ... on Commit { history(first: 25, after: "invalid cursor") { nodes { message } } } } } } }`; try { const result = await graphql(query); } catch (error) { // server responds with // { // "data": { // "repository": { // "name": "probot", // "ref": null // } // }, // "errors": [ // { // "type": "INVALID_CURSOR_ARGUMENTS", // "path": [ // "repository", // "ref", // "target", // "history" // ], // "locations": [ // { // "line": 7, // "column": 11 // } // ], // "message": "`invalid cursor` does not appear to be a valid cursor." // } // ] // } console.log("Request failed:", error.request); // { query, variables: {}, headers: { authorization: 'token secret123' } } console.log(error.message); // `invalid cursor` does not appear to be a valid cursor. console.log(error.data); // { repository: { name: 'probot', ref: null } } }
You can pass a replacement for the built-in fetch implementation as request.fetch
option. For example, using fetch-mock works great to write tests
const assert = require("assert"); const fetchMock = require("fetch-mock/es5/server"); const { graphql } = require("@octokit/graphql"); graphql("{ viewer { login } }", { headers: { authorization: "token secret123" }, request: { fetch: fetchMock .sandbox() .post("https://api.github.com/graphql", (url, options) => { assert.strictEqual(options.headers.authorization, "token secret123"); assert.strictEqual( options.body, '{"query":"{ viewer { login } }"}', "Sends correct query" ); return { data: {} }; }) } });