FAQs

1. An IBM IWHI account with an active subscription
2. Provision the IBM API Connect for GraphQL capability in IBM IWHI (requires iPaaS admin or owner privileges)
3. After provisioning, access your environment by clicking the IBM API Connect for GraphQL link in the 'My capabilities' section on the home page
4. Then use the CLI tool to build, deploy, and test your GraphQL schemas

• An IBM iPaaS account with an active subscription
• A provisioned service instance (environment)
• Appropriate user role assigned by your administrator
• Node.js runtime installed on your machine
• IBM API Connect CLI tools installed
• Account credentials (account name, domain, admin key, and API key)

• Install Node.js from nodejs.org (required for running the CLI)
• Install the CLI via npm:npm install -g stepzen
• Log in to your environment using instance ID
  • For administrators (service owners):

    stepzen login <domain> -i <instance_id>

    When prompted, enter your admin key or IBM SaaS Console API key.
  • For service users:

    stepzen login -i <instance_id> -k <mcsp_apiKey>

• Initialize your workspace: stepzen init
• Deploy your schema: stepzen deploy
• (Optional) Customize CLI configuration as needed. For more information, see Configuring the schema.

There are two ways to create a GraphQL schema:

• Auto-generate using the CLI:
  • Use stepzen import commands to introspect your backend data sources
  • Supports REST APIs, MySQL, PostgreSQL, and GraphQL backends
  • The CLI automatically generates the schema
• Write manually using SDL:
  • Create a .graphql file using GraphQL Schema Definition Language (SDL)
  • Use custom directives to connect to backends:
    • @rest for REST APIs
    • @dbquery for SQL databases
    • @graphql for GraphQL APIs
    • @materializer for advanced field resolution

Deploy your schema:

• Run stepzen deploy to deploy your schema to the server
• Test your API using the GraphiQL explorer (web or local)

For more information, see Creating a GraphQL schema.

Custom directives are declarative annotations in your GraphQL schema that extend functionality and simplify how you build GraphQL APIs. IBM API Connect for GraphQL provides several custom directives for connecting to backend data sources:

Primary Connection Directives:

@rest - Connects to REST APIs

type Query {
customer(id: ID): Customer
@rest(endpoint: "https://api.example.com/customers/$id")
}

@dbquery - Connects to SQL databases (MySQL, PostgreSQL, Oracle, Db2, etc.)

type Query {
orders(customerId: ID): [Order]
@dbquery(type: "mysql", table: "orders")
}

@graphql - Connects to other GraphQL APIs

type Query {
spacexMissions: [Mission]
@graphql(endpoint: "https://api.spacex.land/graphql")
}

Advanced Directives:

@materializer - Links types and stitches data from multiple sources

Important: Does NOT directly connect to backends

extend type Customer {
orders: [Order]
@materializer(query: "orders", arguments: [{name: "customerId", field: "id"}])
}

This executes the existing orders query using data from the Customer type.

@sequence - Executes multiple queries in sequence

Mixes data from multiple sources

These directives enable seamless, declarative data integration without writing resolver code. For more information, see Custom directives.

IBM API Connect for GraphQL supports the following backend data sources:

RESTful APIs:

• Any REST API
• REST interfaces on NoSQL databases

Relational Databases:

• MySQL
• PostgreSQL
• Oracle
• DB2
• Microsoft SQL Server (MSSQL)
• Snowflake
• Trino
• Presto
• SingleStore

GraphQL APIs:

• Third-party GraphQL endpoints
• Other GraphQL APIs

SOAP/XML:

• SOAP services (via @rest directive with postbody)

Connection Methods:

• Use @rest directive for REST APIs and SOAP
• Use @dbquery directive for SQL databases
• Use @graphql directive for GraphQL APIs
• Use stepzen import CLI commands to auto-generate schemas

There are two methods to connect to MySQL or PostgreSQL databases:

Method 1: Auto-Generate (Recommended)

Use the CLI to automatically introspect your database and generate the GraphQL schema:

# For MySQL
stepzen import mysql

# For PostgreSQL
stepzen import postgresql

The CLI will:

• Prompt for database connection details
• Introspect your database tables and columns
• Auto-generate GraphQL types and queries
• Create config.yaml with database configuration

Then deploy with:

stepzen start

Method 2: Manual Schema with @dbquery Directive

1. Create a .graphql file with your schema using the @dbquery directive
2. Create a config.yaml file with database credentials (DSN for MySQL, URI for PostgreSQL)
3. Deploy with stepzen start

For detailed step-by-step instructions, see:

• Tutorial: Create a GraphQL API for a MySQL database
• Tutorial: Create a GraphQL API for a PostgreSQL database

To deploy your GraphQL endpoint with any datasource, use the StepZen CLI command:

stepzen deploy

This command will:

• Package your GraphQL schema files
• Upload them to the IBM API Connect for GraphQL server
• Deploy your endpoint and make it accessible via the GraphQL API
• Provide you with the endpoint URL for testing and integration

To use the MCP (Model Context Protocol) endpoint with IBM API Connect for GraphQL:

1. Ensure you have the MCP endpoint URL for your API Connect for GraphQL instance
2. Configure your MCP client to connect to the endpoint
3. Use the MCP protocol to interact with your GraphQL APIs

You can integrate existing GraphQL APIs into IBM API Connect for GraphQL using the @graphql directive or the CLI import command:

Method 1: Using the CLI (Recommended)

stepzen import graphql <graphql-endpoint-url> 

This will:

• Introspect the remote GraphQL API
• Auto-generate the schema with @graphql directives
• Create the necessary configuration files

Method 2: Manual Schema Definition

Create a .graphql file and use the @graphql directive to connect to the external GraphQL API:

type Query {
  spacexMissions: [Mission]
    @graphql(
      endpoint: "https://api.spacex.land/graphql"
      query: "query { launches { mission_name } }"
    )
}

Benefits:

• Combine multiple GraphQL APIs into a unified schema
• Add custom business logic and transformations
• Implement security and access control
• Stitch data from GraphQL APIs with REST APIs and databases

After creating your schema, deploy with:

stepzen deploy

IBM API Connect for GraphQL provides comprehensive support for GraphQL API development through multiple features and capabilities:

Schema Development:

• Auto-generation: Use CLI commands to automatically generate schemas from existing data sources (REST APIs, databases, GraphQL APIs)
• Manual authoring: Write schemas using GraphQL Schema Definition Language (SDL) with custom directives
• Schema stitching: Combine multiple data sources into a unified GraphQL API

Custom Directives:

• @rest - Connect to REST APIs
• @dbquery - Connect to SQL databases
• @graphql - Connect to other GraphQL APIs
• @materializer - Link types and stitch data
• @sequence - Execute queries in sequence

Development Tools:

• CLI: Command-line interface for schema management, deployment, and testing
• GraphiQL Explorer: Interactive query testing and documentation
• Local development: Test schemas locally before deployment

Security and Access Control:

• API key authentication
• JWT-based authentication
• Field-level access policies
• Role-based authorization

Deployment and Management:

• Simple deployment with stepzen deploy
• Environment management
• Version control support
• Configuration management via config.yaml

Method 1: Auto-Generate (Recommended)

1. Import the REST API using the CLI:

   stepzen import curl "https://api.example.com/endpoint" \
   --header "Authorization: Bearer YOUR_TOKEN"

   This introspects the REST API and automatically generates a GraphQL schema.

2. Deploy the schema:

   stepzen deploy

Method 2: Manual Schema Definition

1. Create a .graphql file and define your schema using SDL with the @rest directive:

   type Customer {
   id: ID
   name: String
   email: String
   }
   
   type Query {
   customer(id: ID!): Customer
   @rest(endpoint: "https://api.example.com/customers/$id")
   
   customers: [Customer]
   @rest(endpoint: "https://api.example.com/customers")
   }

2. Deploy the schema:

   stepzen deploy

Key Points:

• Use @rest directive (NOT @materializer) to map REST endpoints to GraphQL fields
• The @rest directive handles the HTTP calls to your REST API
• You can pass parameters, headers, and configure the endpoint URL
• Your REST data is now accessible through GraphQL queries

IBM API Connect for GraphQL provides multiple security mechanisms:

1. CLI Authentication Security
   • Secure login for service users using MCSP credentials:

     stepzen login -i <instance_id> -k <mcsp_apiKey>

     This method secures the CLI session itself before you can deploy or manage schemas.

2. API Keys (Default - Simplest)
   • Use Admin Keys for development (full access)
   • Use API Keys for production (execute queries only)
   • Pass via Authorization header: Authorization: Apikey YOUR_KEY
3. JWT-Based Authentication
   • Configure JWT verification in config.yaml using JWKS endpoint or keys
   • Pass JWT via Authorization header: Authorization: Bearer YOUR_JWT
   • Access JWT claims in field policies for authorization
4. Field Policies (Fine-Grained Control)
   • Define access rules for specific fields in config.yaml
   • Control access based on:
     • Public access (condition: true)
     • JWT presence (condition: "?$jwt")
     • JWT claims/roles (condition: '$jwt.CUSTOM.role: String == "admin"')
   • Implement custom authorization logic without code
5. GraphQL Configuration
   • Disable introspection in production for security
   • Control response formatting

Example config.yaml:

deployment:
  identity:
    jwksendpoint: https://your-idp.com/.well-known/jwks.json
  graphql:
    introspection: false

access:
  policies:
    - type: Query
      rules:
        - fields: [publicData]
          condition: true
        - fields: [adminData]
          condition: '$jwt.role: String == "admin"'
      policyDefault:
        condition: "?$jwt"

You can secure your GraphQL APIs using the following authentication methods:

• API keys – for general client authentication.
• JWT tokens – for secure, token-based access control.
• Admin keys – for privileged or administrative operations.

In modern GraphQL development with IBM API Connect for GraphQL (StepZen), integrating with backend services such as REST, GraphQL, or database endpoints often requires sensitive credentials like API keys, authorization tokens, or custom headers. The --secrets flag ensures these credentials are never written into generated schema files and are instead managed securely in your configuration.

Why you must use --secrets

Without --secrets, any header you pass to an import command—even a temporary test value—gets hardcoded into your .graphql file:

# ❌ Exposed in your schema file!
type Query {
  myQuery: Root
    @rest(
      endpoint: "https://myapi.com/v1"
      headers: [{ name: "Authorization", value: "Bearer 12345-THIS-SECRET-IS-EXPOSED" }]
    )
}

The --secrets flag eliminates this issue by replacing sensitive data with variable references during the introspection process.

What happens when you use --secrets

How to use the --secrets flag

Pass the name of the header (or URL parameter) whose value you want to hide to the --secrets flag.

1. Importing a REST API with a secret header

stepzen import curl https://my-backend.com/api/v1/user \
  --header 'Authorization: Apikey 12345-THIS-IS-A-SECRET' \
  --secrets 'Authorization'

2. Importing a GraphQL API with a secret header

stepzen import graphql https://your-graphql-endpoint/graphql \
  --header 'X-API-KEY: MySuperSecretKey' \
  --secrets 'X-API-KEY'

What happens behind the scenes

When you use --secrets, StepZen automatically updates two files:

The generated config.yaml:

The actual secret value is securely placed in your config.yaml file under a unique, automatically generated variable name:

configurationset:
  - configuration:
      # StepZen inserts the raw value here:
      authorization_416efbc0dc: Apikey 12345-THIS-IS-A-SECRET
      name: curl_import_config

The corresponding secure SDL:

The generated .graphql schema file now references this variable instead of the raw secret:

type Query {
  myQuery: Root
    @rest(
      endpoint: "https://my-backend.com/api/v1/user"
      # The value is now a secure variable reference!
      headers: [{ name: "Authorization", value: "$authorization_416efbc0dc" }]
      configuration: "curl_import_config"
    )
}

Multiple secrets example

You can secure multiple headers or parameters at once:

stepzen import graphql https://example.com/graphql \
  --header 'Authorization: Apikey 1234' \
  --header 'token: my-token-value' \
  --secrets 'Authorization' \
  --secrets 'token'

Key takeaways

• Always use --secrets when importing data sources that require API keys or tokens.
• Manage credentials securely via config.yaml instead of schema files.
• Helps ensure your GraphQL APIs comply with enterprise security standards.
• Add config.yaml to .gitignore to prevent committing secrets to version control.