GraphQL bugfix + query samples

2026-05-12 20:41:06 +02:00
parent 3f2e199ec4
commit 3e0fc96c0e
5 changed files with 491 additions and 3 deletions
--- a/Events.GraphQL/graphql-query-examples.md
+++ b/Events.GraphQL/graphql-query-examples.md
@@ -0,0 +1,392 @@
+# GraphQL Query Examples
+
+The project exposes the GraphQL endpoint at `/graphql`, and in development GraphiQL is available at `/`.
+
+## Defined queries
+
+The following queries are defined in `Queries.cs`:
+
+- `countries`
+- `sports`
+- `people`
+- `peoplePage(pageNumber, pageSize)`
+- `events`
+- `eventsForDate(date)`
+- `registrations`
+
+The `countries`, `sports`, `people`, `events`, `eventsForDate`, and `registrations` queries support:
+
+- paging via `first`, `after`, `last`, `before`
+- filtering via the `where` argument
+- sorting via the `order` argument
+- `totalCount` because it is enabled in paging options
+
+## Basic examples
+
+### 1. Get countries
+
+```graphql
+query {
+  countries(first: 10) {
+    totalCount
+    nodes {
+      code
+      alpha3
+      name
+    }
+  }
+}
+```
+
+### 2. Get sports
+
+```graphql
+query {
+  sports(first: 10, order: [{ name: ASC }]) {
+    nodes {
+      id
+      name
+    }
+  }
+}
+```
+
+### 3. Get people
+
+```graphql
+query {
+  people(first: 10) {
+    totalCount
+    nodes {
+      id
+      firstName
+      lastName
+      email
+      city
+      birthDate
+      countryCode
+    }
+  }
+}
+```
+
+### 4. Get events
+
+```graphql
+query {
+  events(first: 10, order: [{ eventDate: DESC }]) {
+    nodes {
+      id
+      name
+      eventDate
+    }
+  }
+}
+```
+
+### 5. Get registrations
+
+```graphql
+query {
+  registrations(first: 10) {
+    nodes {
+      id
+      registeredAt
+      personId
+      sportId
+      eventId
+    }
+  }
+}
+```
+
+## Filtering and sorting examples
+
+### 6. Countries whose name contains "Bos"
+
+```graphql
+query {
+  countries(
+    first: 10
+    where: { name: { contains: "Bos" } }
+    order: [{ name: ASC }]
+  ) {
+    nodes {
+      code
+      name
+    }
+  }
+}
+```
+
+### 7. People from a specific country
+
+```graphql
+query {
+  people(
+    first: 10
+    where: { countryCode: { eq: "HR" } }
+    order: [{ lastName: ASC }, { firstName: ASC }]
+  ) {
+    totalCount
+    nodes {
+      id
+      firstName
+      lastName
+      city
+      countryCode
+    }
+  }
+}
+```
+
+### 8. People born after a given date
+
+```graphql
+query {
+  people(
+    first: 10
+    where: { birthDate: { gt: "2000-01-01" } }
+    order: [{ birthDate: DESC }]
+  ) {
+    nodes {
+      id
+      firstName
+      lastName
+      birthDate
+    }
+  }
+}
+```
+
+### 9. Events for an exact date
+
+```graphql
+query {
+  eventsForDate(date: "2026-06-15", first: 20) {
+    totalCount
+    nodes {
+      id
+      name
+      eventDate
+    }
+  }
+}
+```
+
+### 10. Events whose name contains a word
+
+```graphql
+query {
+  events(
+    first: 10
+    where: { name: { contains: "Open" } }
+    order: [{ eventDate: ASC }]
+  ) {
+    nodes {
+      id
+      name
+      eventDate
+    }
+  }
+}
+```
+
+### 11. Registrations with nested data
+
+```graphql
+query {
+  registrations(first: 10, order: [{ registeredAt: DESC }]) {
+    nodes {
+      id
+      registeredAt
+      person {
+        id
+        firstName
+        lastName
+      }
+      sport {
+        id
+        name
+      }
+      event {
+        id
+        name
+        eventDate
+      }
+    }
+  }
+}
+```
+
+## Paging examples
+
+### 12. `pageInfo` for cursor paging
+
+```graphql
+query {
+  people(first: 5, order: [{ id: ASC }]) {
+    totalCount
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      id
+      firstName
+      lastName
+    }
+  }
+}
+```
+
+### 13. Next page using a cursor
+
+```graphql
+query {
+  people(first: 5, after: "PUT_END_CURSOR_HERE") {
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      id
+      firstName
+      lastName
+    }
+  }
+}
+```
+
+### 14. Custom page query `peoplePage`
+
+This query does not use cursor paging. It uses classic `pageNumber` and `pageSize`.
+
+```graphql
+query {
+  peoplePage(pageNumber: 2, pageSize: 5) {
+    totalCount
+    pageNumber
+    pageSize
+    items {
+      id
+      firstName
+      lastName
+      email
+    }
+  }
+}
+```
+
+## Examples with variables
+
+### 15. `eventsForDate` with variables
+
+```graphql
+query EventsForDate($date: Date!) {
+  eventsForDate(date: $date, first: 20) {
+    nodes {
+      id
+      name
+      eventDate
+    }
+  }
+}
+```
+
+Variables:
+
+```json
+{
+  "date": "2026-06-15"
+}
+```
+
+### 16. `peoplePage` with variables
+
+```graphql
+query PeoplePage($pageNumber: Int!, $pageSize: Int!) {
+  peoplePage(pageNumber: $pageNumber, pageSize: $pageSize) {
+    totalCount
+    pageNumber
+    pageSize
+    items {
+      id
+      firstName
+      lastName
+    }
+  }
+}
+```
+
+Variables:
+
+```json
+{
+  "pageNumber": 1,
+  "pageSize": 10
+}
+```
+
+## Existing mutations
+
+Even though this document focuses on queries, the project also defines these mutations for the `Event` entity:
+
+- `addEvent(input)`
+- `updateEvent(id, input)`
+- `deleteEvent(id)`
+
+### 17. Add an event
+
+```graphql
+mutation {
+  addEvent(input: { name: "Street Basketball 2026", eventDate: "2026-07-01" }) {
+    id
+    name
+    eventDate
+  }
+}
+```
+
+### 18. Update an event
+
+```graphql
+mutation {
+  updateEvent(
+    id: 1
+    input: { name: "Street Basketball 2026", eventDate: "2026-07-02" }
+  ) {
+    id
+    name
+    eventDate
+  }
+}
+```
+
+### 19. Delete an event
+
+```graphql
+mutation {
+  deleteEvent(id: 1)
+}
+```
+
+## Fields by type
+
+Useful fields visible from the models:
+
+- `Country`: `code`, `alpha3`, `name`, `translations`
+- `Sport`: `id`, `name`
+- `Person`: `id`, `firstName`, `lastName`, `firstNameTranscription`, `lastNameTranscription`, `addressLine`, `postalCode`, `city`, `addressCountry`, `email`, `contactPhone`, `birthDate`, `documentNumber`, `countryCode`
+- `Event`: `id`, `name`, `eventDate`
+- `Registration`: `id`, `personId`, `sportId`, `eventId`, `registeredAt`
+
+## Source
+
+Examples are based on the implementation in:
+
+- `Events.GraphQLServer/SetupGraphQL/Queries.cs`
+- `Events.GraphQLServer/SetupGraphQL/Mutations.Event.cs`
+- `Events.GraphQLServer/SetupGraphQL/PeoplePage.cs`
+- `Events.GraphQLServer/SetupGraphQL/EventInput.cs`
+- `Events.EF/Models/*.cs`