Skip to main content

GraphQL Introduction

Introduction​

The Api is written in GraphQL. You can find more information about GraphQL here. Unlike REST, GraphQL offers a strongly typed system for querying data. You can query data with POST requests.

There are no fixed endpoints. You can query any data you need. This means it returns only the values you add in the query.

To get data you need to write queries. These are used to fetch data from the database and are read only.

Sample Query​

query GetOutlets {
  outlets {
    id
    name
  }
}

this would return a json like this:

{
  "data": {
    "outlets": [
      {
        "id": "1",
        "name": "Outlet 1"
      },
      {
        "id": "2",
        "name": "Outlet 2"
      }
    ]
  }
}

Passing Parameters in GraphQL​

In GraphQL, you can pass parameters to your queries to filter and manipulate the data you want to retrieve or modify. Parameters are defined in the query definition and are passed as arguments when the query is executed.

Example Query with Parameters​

Here is an example of a query that takes a parameter:

query GetOutlets($outletId: String!) {
  outlet(where: { id: $outletId }) {
    id
    name
  }
}

This query takes a parameter outletId. And only returns the outlet with the given id.

{
  "data": {
    "outlet": {
      "id": "1",
      "name": "Outlet 1"
    }
  }
}

Using cURL to Execute GraphQL Queries​

You can use cURL to execute GraphQL queries.

Executing a Query​

To execute a query using cURL, you can use the following command:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -H "locale: de" \
  -d '{
    "query": "query { outlets { id name } }"
  }' \
  https://api.zfv.ch/graphql

This command sends a POST request to the GraphQL endpoint with the query in the request body.

Executing a Query with Parameters​

To execute a query with parameters:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -H "locale: de" \
  -d '{
    "query": "query GetOutlet($outletId: String!) { outlet(where: { id: $outletId }) { id name } }",
    "variables": { "outletId": "1" }
  }' \
  https://api.zfv.ch/graphql

Using the API in your project​

There is wide support for GraphQL in many languages. In our projects we use Apollo Client for the frontend. And graphql-request for the backend. But there are many other libraries and tools available. Also for Java, PHP, C# and other languages.

You can find a list of libraries and tools here.