E-Commerce API Example
Complete GraphQL API documentation for an e-commerce platform with products, orders, customers, OAuth2 authentication, and real-time order tracking.
This example demonstrates a complete e-commerce GraphQL API with product catalogue, order management, and customer accounts. It showcases JWT authentication, custom scalars (DateTime, Money, EmailAddress), and real-time subscriptions for inventory and order tracking.
API Overview
The E-Commerce API provides:
- Products - Catalogue browsing with filtering and Relay-style pagination
- Orders - Order creation, retrieval, and status management
- Customers - Account management and order history
- Real-time Updates - Inventory and order status subscriptions
API Definition
The complete API definition includes servers, authentication schemes, custom scalars, directives, and interfaces.
Query Operations
Query operations retrieve data from the catalogue and order system.
Retrieves a paginated list of products with optional filtering. Supports Relay-style cursor-based pagination.
Retrieves a single product by its unique identifier. Returns null if the product does not exist or has been discontinued.
Retrieves all product categories. This is a lightweight query that returns the category hierarchy for navigation purposes.
Retrieves a single order by its unique identifier. Users can only access their own orders unless they have administrative privileges.
Retrieves a single customer by their unique identifier. Requires authentication and appropriate permissions.
Retrieves a paginated list of customers. Restricted to administrative users only.
Retrieves all orders for a specific customer, optionally filtered by status. Useful for order history views.
Mutation Operations
Mutations create and modify data in the system.
Creates a new order for a customer. The order is initially created in PENDING status and must have at least one item. Stock is reserved upon order creation.
Creates a new customer account. The email address must be unique. A welcome email is sent upon successful creation.
Creates a new product in the catalogue. Requires administrative privileges. The product is created in DRAFT status by default.
Updates an existing product. Only provided fields are updated; omitted fields retain their current values.
Updates the status of an order. Valid transitions are: PENDING→CONFIRMED→SHIPPED→DELIVERED or PENDING→CANCELLED. Returns the updated order with status history.
Adds a new item to an existing order. Only orders in PENDING status can be modified. Stock is reserved for the added item.
Subscription Operations
Subscriptions provide real-time updates via WebSocket connections.
Subscribes to real-time order status updates for a specific order. Emits an event whenever the order status changes, including the new status, previous status, and timestamp.
Subscribes to real-time inventory updates for a specific product or all products. Emits events when stock quantities change due to orders, restocking, or manual adjustments.
Subscribes to real-time notifications when new orders are created. Useful for order management dashboards and fulfilment systems. Can optionally filter by customer ID.
What This Example Demonstrates
| Feature | How It's Used |
|---|---|
| JWT Bearer Authentication | All operations require JWT tokens by default |
| API Key Fallback | Service-to-service communication via X-API-Key header |
| Custom Scalars | DateTime for timestamps, Money for prices, EmailAddress for contacts |
| Relay Pagination | Products and customers use Relay-style connections |
| Subscriptions | Real-time order status and inventory updates via WebSocket |
| Custom Directives | @auth for authorisation, @cacheControl for caching |
| Interfaces | Node for global IDs, Timestamped for audit trails, Connection for pagination |