What is GraphQL? 🔍

GraphQL Logo

GraphQL is a query language for APIs and a runtime for fulfilling those queries with our existing data. GraphQL provides a complete and understandable description of the data in our API and gives the Yoli API clients the power to ask for exactly what they need and nothing more.

GraphQL is convenient and very easy to learn. The query language is similar to JSON and basicly describes what data is expected in the response. The response itself is common JSON.

For a deeper understanding, we recommend to read the official GraphQL documentation.

Ask for What You Need

Send a GraphQL query to the Yoli API and get exactly what you need, nothing more and nothing less. Our GraphQL queries always return predictable results. Clients using our GraphQL API are fast and stable because they control the data they get, not the server.

Example query that you send to the Yoli API.

{
  bankSearch(search: "N26") {
    shortName
    city
  }
}

Response from the Yoli API containing exactly what you need.

{
  "data": {
    "bankSearch": [
      {
        "shortName": "N26 Bank Berlin",
        "city": "Berlin"
      }
    ]
  }
}

Type System

GraphQL APIs are organized in terms of types and fields, not endpoints. From a single endpoint, your clients can access the full range of the data. Even better: the clients can access exactly the snippet of the data that is needed for each situation! GraphQL uses types to ensure Apps only ask for what’s possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.

In our banksearch example, the returned type is Bank. Yoli's GraphQL schema defines which kinds of fields a Bank has and the clients can query for those. Each field has again a type and possible subfields that can be specified in a query.

  • You can use the GraphiQL App to explore the types and fields of Yoli!

Scalar Types

A GraphQL object type has a name and fields, but at some point those fields have to resolve to some concrete data. That's where the scalar types come in: they represent the leaves of the query.

In our banksearch example, the fields shortName and city resolve to scalar types:

{
  bankSearch(search: "N26") {
    shortName
    city
  }
}

Response data:

{
  "data": {
    "bankSearch": [
      {
        "shortName": "N26 Bank Berlin",
        "city": "Berlin"
      }
    ]
  }
}

We know this because those fields don't have any sub-fields - they are the leaves of the query.

GraphQL comes with a set of default scalar types out of the box:

  • Int: A signed 32‐bit integer.
  • Float: A signed double-precision floating-point value.
  • String: A UTF‐8 character sequence.
  • Boolean: true or false.
  • ID: The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable.

Non-null types are marked with an !. For example, the search parameter in our banksearch query is of the non-nullable scalar type String! and thus, cannot be omitted.

It is also possible to specify collections of a type with the list modifier [], for example the return type of the banksearch query is a list of Bank objects: [Bank].

You can even customize the naming of the fields in a result by using aliases. By preceding a field in a query with <alias>:, the field will be renamed in the resonse data. For example, we could rename the shortName field in our banksearch to "bankName":

{
  bankSearch(search: "N26") {
    bankName: shortName
    city
  }
}

Response data:

{
  "data": {
    "bankSearch": [
      {
        "bankName": "N26 Bank Berlin",
        "city": "Berlin"
      }
    ]
  }
}