GraphQL¶

What is it?¶

GraphQL is a new way to think about building and querying APIs. Rather than construct several REST requests to fetch data that you’re interested in, you can often make a single call to fetch the information you need. Additionally you can specify exactly which fields you want included in the response.

GraphQL is, above all, a querying language, and the format of the query you send matches the data you receive. The language has a schema that strongly types the exchange between client and server.

Query overview¶

GraphQL is hierarchical. Fields between curly braces – which are also at the next level of indent – are part of the enclosing type. For example, profileUrl and urn are fields available as part of the socialAccounts type and name is a part of businessModels.

The query below also demonstrates using GraphQL fragments on socialAccounts to query for information specific to a sub-type. In this case, when the socialAccounts sub-type is FacebookAccount – and only when it’s FacebookAccount – we want to request the current likes count.

query {
    organization(domain:"mattermark.com") {
        name
        socialAccounts {
            urn
            profileUrl
            ... on FacebookAccount {
                likes {
                    current
                }
            }
        }
        products {
            name
            platforms {
                urn
            }
        }
        businessModels {
            name
        }
        industries {
            name
        }
        organizationMetrics {
            growthScore {
                current
                points(limit: 2) {
                    value
                    at
                }
            }
        }
    }
}

your response returns:

{
  "data": {
    "organization": {
      "name": "Mattermark",
      "socialAccounts": [
        {
          "urn": "urn:social:twitter",
          "profileUrl": "https://twitter.com/mattermark"
        },
        {
          "urn": "urn:social:facebook",
          "profileUrl": "https://facebook.com/mattermark",
          "likes": {
            "current": 4182
          }
        },
        {
          "urn": "urn:social:linkedin",
          "profileUrl": "https://linkedin.com/3182754"
        }
      ],
      "products": [
        {
          "name": "Mattermark",
          "platforms": [
            {
              "urn": "urn:platform:mobile:ios:itunes"
            }
          ]
        }
      ],
      "businessModels": [
        {
          "name": "B2B"
        },
        {
          "name": "SaaS"
        }
      ],
      "industries": [
        {
          "name": "analytics"
        },
        {
          "name": "consulting and research"
        },
        {
          "name": "enterprise software"
        },
        {
          "name": "finance"
        },
        {
          "name": "human resources hr"
        },
        {
          "name": "machine learning"
        },
        {
          "name": "market research"
        },
        {
          "name": "search"
        }
      ],
      "organizationMetrics": {
        "growthScore": {
          "current": 75,
          "points": [
            {
              "value": 75,
              "at": "2016-12-11T00:00"
            },
            {
              "value": 89,
              "at": "2016-12-04T00:00"
            }
          ]
        }
      }
    }
  }
}

Why are we using GraphQL?¶

We’re supporting GraphQL because it offers much more flexibility than a traditional REST interface. GraphQL natively supports performing an introspection query which allows the API to more fully discoverable and easier to integrate against. The ability to define and specify precisely the data you want for your integration is a powerful advantage over the existing REST endpoints. Through fragments and template variables it simplifies many aspects of the client-side integration process. Additionally, because it’s a recognized spec, there are many client libraries and tools to assist you in quickly getting up and running.

Additional Resources¶

Below is some optional reading material that might help you go deeper into the GraphQL ecosystem: