Skip to main content

Using the SGS GraphQL API

Yaniv Navon
  • Updated

In this article:

Starting with SkylineGlobe Server 8.5, the SGS GraphQL API provides query-based access to server data through a single endpoint. You can use the built-in Nitro GraphQL IDE to explore the schema and test operations, or send authenticated GraphQL requests from an application.

GraphQL replaces the legacy REST API used in earlier SGS versions. It supports queries that retrieve data and mutations that create, update, or delete server resources, subject to the signed-in user's permissions.

Prerequisites

  • SkylineGlobe Server 8.5 or later
  • An SGS user account with permission to access the requested resources

The GraphQL endpoint is:

https://[SGS_SERVER_URL]/graphql

Explore the API with Nitro

Nitro, the GraphQL IDE included with SGS, provides an operation builder, schema browser, request editor, and response viewer.

  1. Sign in to SGS at https://[SGS_SERVER_URL]/Admin/Login. 
  2. Open the GraphQL endpoint in the same browser session.
  3. Click Create Document.
  4. On the Operation tab, open the Operation Builder.
  5. Click +, and then select one of the following:
    • New Query to retrieve information
    • New Mutation to create, update, or delete data
  6. Enter a name for the operation, and then press Enter.
  7. Expand the operation in the Builder panel and select the query or mutation you want to run.
  8. Select the fields to return and enter any required parameter values.
  9. Click Run. Nitro displays the result in the Response panel.

Note: Nitro uses the SGS authentication cookie from the current browser session, so a separate Nitro sign-in is not required.

Query Example

The following query retrieves selected Help settings:

query GetHelpSettings {
  HelpSettings {
    allowExternalLinks
    errorMessage
    knowledgeBaseURL
    videoTutorialsURL
  }
}

A GraphQL query returns only the fields included in the request.

Mutation Example

The following mutation adds a category:

mutation AddCategory {
  AddCategory(
    categoryInputDto: {
      name: "category1"
    }
  ) {
    actionResultDtoList {
      errorMessage
      key
      successStatus
    }
  }
}

The response indicates whether the operation succeeded and includes any validation or error information returned by SGS.

Use Query Variables

For reusable operations, define variables instead of hardcoding values in the query. You can run the same query with different values by changing the variables without modifying the query itself.

Query

query SiteById($id: UUID!) {
  Site(id: $id) {
    id
    name
    description
  }
}

Variables

{
  "id": "SITE-ID-GOES-HERE"
}

Access the API Programmatically

A server-side application must include a valid SGAuth cookie in each GraphQL request. The login endpoint is site-specific:

https://[SGS_SERVER_URL]/[SITE_NAME]/ConnectSG

To access the API programmatically:

  1. Authenticate with SGS.
  2. Retrieve the SGAuth cookie from the login response.
  3. Send the cookie with a query to the GraphQL endpoint.
  4. Process the data returned by SGS.
// loginAndQuery.js
// Requires Node.js 18 or later.

const sgsBaseUrl = 'https://[SGS_SERVER_URL]';
const siteName = 'Default';

const loginPayload = {
  request: 'login',
  username: '[USERNAME]',
  password: '[PASSWORD]',
  isPersistent: false
};

const query = `
  query GetSites {
    Sites {
      errorMessages
      totalSites
      siteDtoList {
        id
        name
        isActive
      }
    }
  }
`;

async function loginAndQuery() {
  const loginUrl =
    `${sgsBaseUrl}/${encodeURIComponent(siteName)}/ConnectSG`;

  // Authenticate with SGS
  const loginResponse = await fetch(loginUrl, {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(loginPayload)
  });

  if (!loginResponse.ok) {
    throw new Error(`Login failed: ${loginResponse.status}`);
  }

  // Extract the SGAuth cookie from the login response
  // getSetCookie() is available in newer Node.js versions. The fallback
  // supports versions that expose the Set-Cookie header through get().
  const setCookieHeaders =
    typeof loginResponse.headers.getSetCookie === 'function'
      ? loginResponse.headers.getSetCookie()
      : [loginResponse.headers.get('set-cookie')].filter(Boolean);

  const sgAuthCookie = setCookieHeaders
    .flatMap(header => header.split(/,(?=\s*[^;,\s]+=)/))
    .map(cookie => cookie.trim())
    .find(cookie => cookie.startsWith('SGAuth='));

  if (!sgAuthCookie) {
    throw new Error(
      'The SGS login response did not include an SGAuth cookie.'
    );
  }

  const cookieHeader = sgAuthCookie.split(';', 1)[0];

  // Send an authenticated GraphQL query
  const graphQLResponse = await fetch(`${sgsBaseUrl}/graphql`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Cookie: cookieHeader
    },
    body: JSON.stringify({ query })
  });

  if (!graphQLResponse.ok) {
    throw new Error(
      `GraphQL request failed: ${graphQLResponse.status}`
    );
  }

  const result = await graphQLResponse.json();

  if (result.errors?.length) {
    throw new Error(JSON.stringify(result.errors, null, 2));
  }

  // Process the returned site information
  const sites = result.data?.Sites?.siteDtoList ?? [];

  sites.forEach((site, index) => {
    console.log(
      `${index + 1}. ${site.name} (${site.id}) - Active: ${site.isActive}`
    );
  });
}

loginAndQuery().catch(error => {
  console.error('Error:', error.message);
  process.exitCode = 1;
});

Security: Do not hardcode production credentials in source code or log the SGAuth cookie. Store credentials using an appropriate secrets-management method.

For additional information, see Accessing the SGS API in the SkylineGlobe Server User Guide.

Related articles