====== 3.1 GraphQL Basics ======

GraphQL((GraphQL Specification: https://spec.graphql.org/)) enables flexible, precise data queries.

===== What is GraphQL? =====

GraphQL((GraphQL Foundation: https://graphql.org/)) is a query language for APIs and a runtime for executing these queries. Unlike REST((Representational State Transfer: https://en.wikipedia.org/wiki/Representational_state_transfer)), clients can request exactly the data they need.

===== Endpoint =====

<code>
POST /api/v1/dsn/{dbName}/graphql
Content-Type: application/json
</code>

===== Simple Query =====

<code javascript>
{
  "query": "{ customers { id name country } }"
}
</code>

===== With Parameters =====

<code javascript>
{
  "query": "{ customers(first: 10, filter: \"Country eq 'DE'\") { id name } }"
}
</code>

===== Retrieve Schema =====

<code>
GET /api/v1/dsn/demo/graphql/schema
</code>

Returns the GraphQL schema in SDL((Schema Definition Language: https://graphql.org/learn/schema/)) format.

===== Advantages Over REST =====

^ Aspect ^ REST ^ GraphQL ^
| Endpoints | Many (per resource) | One |
| Over-fetching | Common | Never |
| Under-fetching | Common (N+1) | Never |
| Type safety | Optional | Built-in |
| Documentation | External (OpenAPI((OpenAPI Specification: https://www.openapis.org/))) | Integrated (Introspection) |

===== Sources =====

  * [[https://graphql.org/|GraphQL Foundation - Official Website]]
  * [[https://spec.graphql.org/|GraphQL Specification]]
  * [[https://graphql.org/learn/|GraphQL Learn]]