About GraphQL

GraphQL is a query language for your API and a server-side runtime for executing queries by using a type system that you define for your data.

For more information please refer to https://graphql.org/learn/

Fields

To simplify, GraphQL allows you to ask for specific fields on objects. Let's start by looking at a very simple query and the result we get when we run it:

{
    company {
        displayName
        locationsCount
        homepage
    }
}

The response:

{
    "data": {
        "company": {
            "displayName": "Stripe",
            "homepage": "https://stripe.com",
            "locationsCount": 13
        }
    }
}

You can see that the query reflects the same structure as the result. This is essential to GraphQL, because the server knows exactly what fields you are asking for and you always get back what you expect.

In the previous example, we just asked for the display name of the company which returned a String, but fields can also refer to Objects. In that case, you can make a sub-selection of fields for that Object. GraphQL queries can traverse related objects and their fields, letting clients fetch a significant amount of related data in one request, instead of making several requests as one would need in a classic REST architecture:

{
    company {
        displayName

        locations {
            city
            country
        }
    }
}

That will return:

{
    "data": {
        "company": {
            "displayName": "Stripe",
            "locations": [
                {
                    "city": "San Francisco",
                    "country": "US"
                },
                {
                    "city": "Chicago",
                    "country": "US"
                },
                
            ]
        }
    }
}

Arguments

In a system like REST, you can only pass a single set of arguments - the query parameters and URL segments in your request. But in GraphQL, every field and nested object can have its own set of arguments, making GraphQL a complete replacement for making multiple API fetches:

{
    company(duns: "966357621") {
        displayName
        locationsCount
        homepage
    }
}

Variables

In most applications, the arguments to fields will be dynamic. For example, you might be requesting a list of companies by DUNS, which changes in each request.

It wouldn't be a good idea to pass these dynamic arguments directly in the query string, because then our client-side code would need to dynamically manipulate the query string at runtime, and serialize it into a GraphQL-specific format. Instead, GraphQL has a first-class way to factor dynamic values out of the query, and pass them as a separate dictionary. These values are called variables.

Query:

query findCompanyByDUNS($duns: String!) {
    company(duns: $duns) {
        displayName
        locationsCount
        homepage
    }
}

Variables:

{ "duns": "966357621" }

Enumeration types

Also called Enums, enumeration types are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to:

1. Validate that any arguments of this type are one of the allowed values

2. Communicate through the type system that a field will always be one of a finite set of values

Here's what an enum definition might look like in the GraphQL schema language:

enum CompanyTypeEnum {
    investor
    private
    public
    subsidiary
}

Make you first call to the Company Data API:

Getting started with JavaScript