GraphQL within the consumer loans APIs

General

GraphQL is becoming more and more important in Europace’s APIs and especially in consumer loans. One of the special features of GraphQL is that you explicitly state which data you need. Depending on the implementation of the API, you can achieve the best possible performance in processing the request by limiting it to the most important fields in the request. Another advantage of GraphQL is that you can get a lot of resources with one request. If you need case and offer data, for example, you can do this with just one GraphQL query in the KEX-process-export-API. With REST-APIs, several requests would normally be necessary. Several queries can also be sent at the same time, which are then processed in parallel. For example, if you want to get data of five cases, you can query this in a single request with five GraphQL queries.

Queries

GraphQL queries are used to query data. This can be compared to a GET request in REST.

Mutations

GraphQL mutations are used to create or change data. This can be compared to a POST request in REST.

Tools

There are many tools that enable the user to explore an API using GraphQL introspection. These tools make it very easy, e.g. through auto-completion, to assemble a GraphQL query that can then be used in the code.

Altair

Link: https://altair.sirmuel.design/

Altair is a very powerful and easy-to-use rich client for GraphQL. It supports auto-completion, environment variables, headers, and much more. The client is available for common operating systems. For users who do not want to install an additional application, there is also a web client or extensions for various browsers available.

Altair Client

GraphiQL

Link: https://www.electronjs.org/apps/graphiql

GraphiQL is one of the most popular clients for GraphQL. It is mainly used as a Chrome extension. A rich client for macOSX and Linux is also available.

Error handling

In addition to the usual HTTP status codes, there is another way of returning errors in GraphQL.

In many cases an HTTP status of 200 is returned even though an error has occurred. For this there is the attribute errors in the response (for more information see here).

Validation Error

If the GraphQL query cannot be processed, a response with errorType ValidationError is returned.

In the example, the query of the KEX-process-export-API was executed, but the field vorgangsnummer was misspelled (vorgangsnummerr).

{
  "errors": [
    {
      "message": "Validation error of type FieldUndefined: Field 'vorgangsnummerr' in type 'Vorgang' is undefined @ 'vorgang/vorgangsnummerr'",
      "locations": [
        {
          "line": 1,
          "column": 89
        }
      ],
      "description": "Field 'vorgangsnummerr' in type 'Vorgang' is undefined",
      "validationErrorType": "FieldUndefined",
      "queryPath": [
        "vorgang",
        "vorgangsnummerr"
      ],
      "errorType": "ValidationError"
    }
  ]
}

More errors

If the request could not be processed successfully, the interface returns an HTTP status code 200, but error details can be found in the errors attribute:

{
  "data": {},
  "errors": [
    {
      "message": MESSAGE,
      "status": STATUS_CODE
    }
  ]
}

However, depending on the API implementation, data can still be returned if only part of the data is affected by an error. A typical example for this are access rights.

Therefore it is particularly important for GraphQL clients to not only look at the HTTP status, but to also analyze the errors attribute.

More information