A powerful and intuitive Python library for building GraphQL APIs with a code-first, decorator-based approach.

GraphQL API for Python#

PyPI version Python versions License: MIT

Why GraphQL API?#

graphql-api simplifies schema definition by leveraging Python’s type hints, dataclasses, and Pydantic models, allowing you to build robust and maintainable GraphQL services with minimal boilerplate.

Key Features#

FeatureDescription
🎯 Code-First ApproachDefine your GraphQL schema using Python decorators and type hints. No SDL required.
⚡ Type SafetyAutomatic type conversion from Python types to GraphQL types with full type checking support.
🔄 Async SupportBuilt-in support for async/await patterns and real-time subscriptions.
🧩 Pydantic IntegrationSeamlessly use Pydantic models and dataclasses as GraphQL types.
🌐 Federation ReadyBuilt-in Apollo Federation support for microservice architectures.
🎛️ Flexible SchemaChoose between unified root types or explicit query/mutation/subscription separation.

Quick Start#

Get up and running in minutes:

pip install graphql-api
from graphql_api.api import GraphQLAPI

# Initialize the API
api = GraphQLAPI()

# Define your schema with decorators
@api.type(is_root_type=True)
class Query:
    @api.field
    def hello(self, name: str = "World") -> str:
        return f"Hello, {name}!"

# Execute queries
result = api.execute('{ hello(name: "Developer") }')
print(result.data)  # {'hello': 'Hello, Developer!'}

graphql-api focuses on schema definition and execution. For additional functionality:

HTTP Server: graphql-http#

Serve your GraphQL API over HTTP with graphql-http:

  • 🚀 High-performance ASGI server built on Starlette
  • 🔐 JWT authentication with JWKS support
  • 🎨 Integrated GraphiQL interface
  • 🌐 CORS support and health checks
from graphql_api import GraphQLAPI
from graphql_http import GraphQLHTTP

api = GraphQLAPI()
# ... define your schema ...

server = GraphQLHTTP.from_api(api)
server.run()

Learn more: graphql-http documentation

Database Integration: graphql-db#

Build database-backed APIs with SQLAlchemy using graphql-db:

from graphql_api import GraphQLAPI
from graphql_db.orm_base import DatabaseManager, ModelBase

# Define models and create API
api = GraphQLAPI()
# ... graphql-db handles database integration ...

Learn more: graphql-db documentation

MCP Tools: graphql-mcp#

Expose your GraphQL API as MCP tools for AI agents with graphql-mcp:

from graphql_api import GraphQLAPI
from graphql_mcp.server import GraphQLMCP

api = GraphQLAPI()
# ... define your schema ...

server = GraphQLMCP.from_api(api)
app = server.http_app()

Learn more: graphql-mcp documentation

Key Features#

  • Decorator-Based Schema: Define your GraphQL schema declaratively using simple and intuitive decorators
  • Type Hinting: Automatically converts Python type hints into GraphQL types
  • Implicit Type Inference: Automatically maps Pydantic models, dataclasses, and classes with fields
  • Pydantic & Dataclass Support: Seamlessly use Pydantic and Dataclass models as GraphQL types
  • Asynchronous Execution: Full support for async and await for high-performance, non-blocking resolvers
  • Apollo Federation: Built-in support for creating federated services
  • Subscriptions: Implement real-time functionality with GraphQL subscriptions
  • Middleware: Add custom logic to your resolvers with a flexible middleware system
  • Relay Support: Includes helpers for building Relay-compliant schemas

What’s Next?#

  • 📚 Getting Started - Learn the basics with our comprehensive guide
  • 💡 Examples - Explore practical examples and tutorials for real-world scenarios
  • 📖 API Reference - Check out the complete API documentation