Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Learn best practices and considerations for migrating from Scope's REST API to Scope's GraphQL API.

In this article

Table of Contents

Differences in API logic

Migrating from REST to GraphQL represents a significant shift in API logic. The differences between REST as a style and GraphQL as a specification make it difficult—and often undesirable—to replace REST API calls with GraphQL API queries on a one-to-one basis. We've included specific examples of migration below.

...

  • Review the GraphQL spec

  • Review Scope's GraphQL schema

  • Consider how any existing code you have currently interacts with the Scope REST API

  • Use Global Node IDs to reference objects between API versions

...

Code Block
query {
  viewer {
    organization {
      members(first: 10) {
        edges {
          node {
            name
            avatar { 
              fileUrl
            }
          }
        }
      }
    }
  }
}

Example #2: Nesting

Querying with nested fields lets you replace multiple REST calls with fewer GraphQL queries. For example, retrieving a scenario along with its ar contents and associated groups using the REST API requires four separate calls:

...

Code Block
{
  node(id: "ID_OF_SCENARIO")
    ... on Scenario
      name
      content {
        fileUrl
        fileContentType
        fileUrlExpiresAt
      }
      groups {
        nodes {          
          id
          name
        }
      }
    }
  }
}

You can also extend the power of this query by substituting a variable for the pull request number.

...

Code Block
mutation {
  updateScenario(id: "MDA6SXNzdWUyMjcyMDA2MTT", input:{name: 1234}) {
    id
    name
    groups {
      nodes {          
        id
        name
      }
    }
  }
}

Executing this query returns errors specifying the expected types for the operation:

Code Block
{
  "data": null,
  "errors": [
    {
      "message": "Argument 'input' on Field 'name' has an invalid value. Expected type 'String!'.",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ]
    }
  ]
}