APIUsingStrawberry

[fabianabarca]

GraphQL API

Summary

Develop a GraphQL API for Databús using Strawberry GraphQL. The API must expose the main GTFS-related entities, support queries and mutations, include proper authentication and permissions, and provide full test coverage.

Objectives

• Integrate Strawberry into the Django project using uv and the Django integration.
• Create a new Django app named graphql.
• Define the GraphQL schema (Query + Mutation) in graphql/schema.py. Note: a mutation is an operation used to create, update, or delete data on the server.
• Expose the main Databús gtfs app models:
  • Agency
  • Route
  • Stop
  • Trip
  • StopTime
  • ...
• Provide essential queries and at least one mutation in graphql/queries.py.
• Define Strawberry GraphQL types in graphql/types.py.
• Enforce authentication and Django permissions.
• Add comprehensive tests for schema, resolvers, and access control.
• Document how to run and use the API.

Scope

1. Schema Setup

• Install and configure Strawberry in Django using uv and the Django integration.
• Create a root schema with:
  • Query
  • Mutation
• Add endpoint at /graphql/.

2. Query Implementation

Implement queries to read GTFS entities, including:

• allAgencies
• agency(id)
• allRoutes
• allStops
• tripsByRoute(routeId)
• stopTimesByTrip(tripId)

Queries must support:

• Filtering
• Ordering where applicable
• Pagination (relay-style or offset and the selection must be documented)

3. Mutation Implementation

Implement at least one mutation, e.g.:

• createAgency(name, url, timezone, lang?)

The mutation must return:

• The created object
• Validation errors (if any)

4. Permissions and Authentication

• Require authentication for all queries and mutations.
• Restrict write operations to staff or users with Django model permissions.
• Return clear unauthorized error responses.

5. Documentation

Create docs/graphql.md including:

• Running the GraphQL endpoint
• Example queries/mutations
• Authentication
• How to extend the schema

Tests (Deliverables)

Create tests under tests/test_graphql/:

Schema Tests

• Schema loads successfully
• Queries/mutations appear in schema

Query Tests

• Fetching objects
• Pagination
• Filtering
• Auth vs no-auth cases

Mutation Tests

• Successful mutation
• Validation errors
• Permission enforcement

Permission Tests

• Anonymous users blocked
• Non-staff without permissions cannot mutate

Deliverables Checklist

• Strawberry configuration
• schema.py with Queries/Mutations
• Django ORM resolvers
• Permissions integrated
• Tests for queries, mutations, schema, and permissions
• Documentation (docs/graphql.md)
• Code formatted/linted using Ruff (already installed in pyproject.toml)