Welcome to the GraphQL Bookstore API - a deliberately vulnerable API designed for security education and hands-on learning of GraphQL fundamentals. This project provides a realistic bookstore environment where you can explore common web vulnerabilities in a safe, educational setting.

The GraphQL Bookstore API simulates a real-world e-commerce platform built with GraphQL. It includes complete functionality for a bookstore including user accounts, book browsing, shopping cart, order management, product reviews, and webhook notifications. The API is intentionally built with various security vulnerabilities to help developers, security researchers, and students understand and identify common web application security flaws.

This API serves as a learning platform for:

• Understanding GraphQL API security fundamentals
• Learning to identify and exploit common vulnerabilities
• Practicing secure coding techniques
• Testing security tools and methodologies
• Educational workshops and capture-the-flag (CTF) events

The API follows a typical e-commerce workflow:

1. USER REGISTRATION/LOGIN
   └─→ Create account or authenticate to receive JWT token

2. BROWSE BOOKS
   └─→ Query books, search by title/author/category
   └─→ View book details and reviews

3. MANAGE CART
   └─→ Add books to shopping cart
   └─→ Update quantities or remove items
   └──→ Apply coupon codes (discounts)

4. CHECKOUT & PAYMENT
   └─→ Review cart contents
   └─→ Process payment (simulated Vulnbank)
   └─→ Create order record

5. ORDER MANAGEMENT
   └─→ View order history
   └─→ Cancel orders (if allowed)
   └─→ Track order status

6. REVIEWS & RATINGS
   └─→ Submit reviews for purchased books
   └─→ View reviews from other users

7. WEBHOOKS (Optional)
   └─→ Register webhook URLs for real-time notifications
   └─→ Receive events: order created, paid, cancelled, etc.

The GraphQL Bookstore API accepts requests via HTTP POST to the /graphql endpoint. All requests must include a JSON body with a query field containing your GraphQL operation.

You can use either of the following endpoints:

Local Development:  http://localhost:4000/graphql
Live URL: https://api.graphqlbook.org/graphql

// All examples below use localhost. Simply replace with the live URL when ready.

POST /graphql
Content-Type: application/json

{
  "query": "Your GraphQL query or mutation here"
}

curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ books { id title price } }"}'

curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { login(username: \"admin\", password: \"password123\") { success token } }"}'

curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE" \
  -d '{"query":"mutation { addToCart(bookId: 1, quantity: 2) { success } }"}'

fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: '{ books { id title price } }'
  })
})
.then(r => r.json())
.then(d => console.log(d));

// First login to get token, then use it for authenticated requests
const token = 'YOUR_JWT_TOKEN_HERE';

fetch('/graphql', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    query: 'mutation { addToCart(bookId: 1, quantity: 2) { success } }'
  })
})
.then(r => r.json())
.then(d => console.log(d));

Queries are used to fetch data (read operations). Mutations are used to modify data (write operations like creating, updating, or deleting).

# Query - Read data (no exclamation point)
query {
  books { id title price }
}

# Mutation - Write data (starts with mutation keyword)
mutation {
  login(username: "admin", password: "pass") { token }
}

Content-Type: application/json
Authorization: Bearer <your-jwt-token>  // Only for authenticated requests

Successful responses are wrapped in a data object. Errors are returned in an errors array.

// Success Response
{
  "data": {
    "books": [
      { "id": "1", "title": "Book Title", "price": 19.99 }
    ]
  }
}

// Error Response
{
  "errors": [
    { "message": "Authentication required" }
  ]
}

Postman is a popular tool for testing APIs. Here's how to use it with this GraphQL API:

Method: POST

URL: http://localhost:4000/graphql
      (or https://api.graphqlbook.org/graphql for production)

Headers:
Content-Type: application/json
Authorization: Bearer <your-token>  // Only for authenticated requests

Body (JSON):
{
  "query": "{ books { id title price } }"
}

You can also use online GraphQL tools like Apollo GraphQL Studio, Insomnia, or similar:

Apollo GraphQL Studio: https://studio.apollographql.com/sandbox/explore
Insomnia: https://insomnia.rest/download
Postman: https://www.postman.com/downloads

// Simply set the endpoint URL and send your GraphQL query

The API uses JWT (JSON Web Tokens) for authentication. Here's the complete flow:

// Step 1: Login to get your JWT token
mutation {
  login(username: "admin", password: "password123") {
    success
    token
    user {
      id
      username
      role
    }
  }
}

// Step 2: Use the token in subsequent requests
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// Step 3: Token is valid for 6 hours. Include it in the
//         Authorization header for protected endpoints

The API comes with pre-configured test accounts:

Admin:   username: admin   password: password123   role: admin
Staff:   username: staff   password: password123   role: staff
User:    username: user    password: password123   role: user

Run the API directly on your machine. Requires C++ compiler, PostgreSQL, and required libraries.

• C++ compiler (g++)
• PostgreSQL database
• libpq-dev
• libjwt-dev
• libcurl-dev

git clone https://github.com/DghostNinja/graphql-bookstore-API.git
cd GraphQL-Bookstore
./build.sh

./bookstore-server

DOCS: http://localhost:4000
API Endpoint: http://localhost:4000/graphql

Run the API in a Docker container. Easiest way - handles all dependencies automatically.

git clone https://github.com/DghostNinja/graphql-bookstore-API.git
cd GraphQL-Bookstore
docker-compose up --build

DOCS: http://localhost:4000
API Endpoint: http://localhost:4000/graphql

docker-compose down

This section provides an overview of the GraphQL schema, including available data types and how to explore the API using introspection.

The API defines several core types that represent the bookstore data model:

Book         - Represents a book in the catalog
  id, title, description, price, stockQuantity, categoryId, authorId

Author       - Represents a book author
  id, firstName, lastName, biography

User         - Represents a registered user
  id, username, email, role, firstName, lastName, phone, city

Order        - Represents a customer order
  id, orderNumber, userId, status, totalAmount, createdAt, items

OrderItem   - Represents an item in an order
  id, bookId, quantity, price

Cart         - Represents a shopping cart
  id, userId, items, subtotal, tax, discount, total

CartItem     - Represents an item in the cart
  id, bookId, quantity, price

Review       - Represents a book review
  id, bookId, userId, rating, comment, createdAt

Webhook      - Represents a webhook subscription
  id, userId, url, events, secret, isActive

GraphQL allows you to request only the specific fields you need. This reduces response size and improves performance.

query {
  books {
    id
    title
    description
    price
    stockQuantity
    author {
      firstName
      lastName
    }
  }
}

query {
  books {
    id
    title
    price
  }
}

query {
  cart {
    id
    items {
      bookId
      quantity
      book {
        title
        price
      }
    }
  }
}

GraphQL supports introspection, allowing you to query the schema itself to discover available types, fields, and operations.

query {
  __schema {
    types {
      name
      kind
      description
    }
  }
}

query {
  __type(name: "Book") {
    name
    kind
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

query {
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
  }
}

query {
  __schema {
    queryType {
      fields {
        name
        description
        type {
          name
        }
        args {
          name
          type {
            name
          }
        }
      }
    }
  }
}

Many queries accept arguments to filter, sort, or limit results:

books(search: String, categoryId: Int, limit: Int)
  - search: Filter by title or description
  - categoryId: Filter by category
  - limit: Limit number of results

book(id: Int!)
  - id: Required - the book ID

_searchAdvanced(query: String!)
  - query: Search query string

bookReviews(bookId: Int!)
  - bookId: Required - filter reviews by book

Queries are used to fetch data from the API. Some queries require authentication.

Mutations are used to modify data. Most mutations require authentication.

The Bookstore API includes an MCP (Model Context Protocol) server that exposes all API operations as tools for AI and LLM models. This enables AI assistants to interact with the Bookstore API natively.

# Navigate to MCP directory and install
cd mcp
npm install

Local Development:

# Start the Bookstore API server (from project root)
./bookstore-server

# In another terminal, start MCP server
cd mcp
npm start

Production (Live API):

cd mcp
API_URL=https://api.graphqlbook.org/graphql npm start

The MCP server exposes 25 tools organized by category:

Add the following to your Claude Desktop config file:

{
  "mcpServers": {
    "bookstore": {
      "command": "node",
      "args": ["/path/to/GraphQL-Bookstore/mcp/mcp_server.mjs"],
      "env": {
        "API_URL": "http://localhost:4000/graphql"
      }
    }
  }
}

For production, change API_URL to https://api.graphqlbook.org/graphql.

See mcp/README.md for detailed documentation.

Have suggestions, found bugs, or want to share your experience? We'd love to hear from you! Your feedback helps improve this API.