IBM API Connect for GraphQL Software

https://www.ibm.com/docs/en/api-connect-graphql
Admin
IBM API Connect for GraphQL Software is a service that provides capabilities for managing and...
Tokens:392,513
Snippets:2,386
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install and Manage MySQL using Homebrew

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-mysql

Commands to install, verify, start, and access a local MySQL server using Homebrew on macOS. This is the initial setup for the database.

```bash
brew install mysql
```

```bash
mysql --version
```

```bash
brew services start mysql
```

```bash
mysql -u root -p password
```

--------------------------------

### Example Copy Command for ibm-pak Plugin (Linux)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Provides a concrete example of copying the ibm-pak plugin for Linux amd64 architecture to the designated binary directory.

```shell
cp oc-ibm_pak-linux-amd64 /usr/local/bin/kubectl-ibm_pak
```

--------------------------------

### Example Login Command for API Connect for GraphQL CLI

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=setting-up-your-environment

This is an example of the 'stepzen login' command with specific placeholders for the domain and account name, demonstrating how to log into a production environment.

```bash
stepzen login envname.us-east-a.ibm.stepzen.net -a production
```

--------------------------------

### Configuration Set Example (Conditional)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=apis-tutorial-create-graphql-api-graphql-backend

An example of a `config.yaml` file that would be generated if the API required authorization. This file contains configuration information for connecting to backends.

```yaml
configurationset:
  - configuration:
      name: schema_name.graphql_config
```

--------------------------------

### Install k6 Benchmark Tool on Mac

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=schemas-measuring-api-performance

Installs the k6 load testing tool on macOS using the Homebrew package manager. Ensure Homebrew is installed before running this command. This tool is essential for executing the benchmark tests.

```bash
brew install k6
```

--------------------------------

### Example PostgreSQL Connection URI

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-postgresql

Provides a concrete example of a PostgreSQL connection URI, showing how to substitute placeholders with actual credentials and ngrok details.

```text
uri: postgresql://your_username:your_password@2.tcp.ngrok.io:1234/postgres
```

--------------------------------

### Install PostgreSQL using Homebrew

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-postgresql

Installs PostgreSQL on macOS using the Homebrew package manager. This is the first step in setting up the database.

```shell
brew install postgresql
```

--------------------------------

### Start StepZen Development Server

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=locally-using-graphiql-local-api-testing

Command to initiate the StepZen development server, enabling the dashboard for local GraphiQL interface access. This command starts a local proxy that is restricted to requests from the browser workspace.

```bash
stepzen start --dashboard=local
```

--------------------------------

### Install API Connect for GraphQL CLI using npm

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=setting-up-your-environment

This command installs the API Connect for GraphQL command-line interface (CLI) globally using npm. Ensure Node.js is installed as a prerequisite. This command is executed in a terminal.

```bash
npm install -g stepzen
```

--------------------------------

### Start MySQL Server

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=ngrok-using-mysql

This command starts the MySQL service managed by Homebrew. It ensures the database server is running and ready to accept connections. This is a prerequisite for accessing or configuring the database.

```shell
brew services start mysql
```

--------------------------------

### Start PostgreSQL Server using Homebrew

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-postgresql

Starts the PostgreSQL server as a background service managed by Homebrew. This command ensures the database is running.

```shell
brew services start postgresql
```

--------------------------------

### Example API Connect for GraphQL Service URL

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=setting-up-your-environment

This is an example of the service URL for API Connect for GraphQL, showing a fully qualified URL based on a hypothetical environment name and domain.

```text
https://envname.graphserver.apps.my-rosa-cluster.abcd.p1
```

--------------------------------

### Example API Connect for GraphQL CLI Login URL

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=setting-up-your-environment

An example of the login URL for the API Connect for GraphQL CLI, showing the structure with a specific environment name and domain.

```text
https://envname.us-east-a.ibm.stepzen.net
```

--------------------------------

### GraphQL Tool Definition Example

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-directive-tool

An example demonstrating how to define a GraphQL tool that exposes a subset of the schema rooted at `Query.customer`. It also details the parameters available for executing the tool.

```APIDOC
## GraphQL Tool Example

This defines a GraphQL tool that is a subset of the schema rooted at the single field `Query.customer`.

```
extend schema
  @tool(
    name: "customer-lookup"
    description: "Customer lookup tool. {graphql_tool}"
    graphql: {expose: true, types: "Query", fields: "customer"}
  )
```

The schema will include all schema elements reachable from `Query.customer`. The tool has three parameters: `query` (required), `operationName`, and `variables`. It can be executed via the MCP method `tools/call` by providing arguments for a valid GraphQL request against the tool's schema.
```

--------------------------------

### Example Output of Successful Configuration

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=graphql-configuring-api-connect

This is an example output showing a successful configuration of the API Connect for GraphQL Graph Service. The 'STATUS' column indicates 'Ready', and the 'SUMMARY' column confirms that the services are ready.

```text
NAME      STATUS   SUMMARY              AGE
stepzen   Ready    Services are ready   1m
```

--------------------------------

### Start Local API Connect for GraphQL Service

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=environment-using-docker-local-api-development

Initiates a local API Connect for GraphQL service instance using the command-line interface. This command starts the service in a Docker container and creates a local configuration file, `~/.stepzen/stepzen-config.local.yaml`.

```bash
stepzen service start
```

--------------------------------

### Execute Example GraphQL Queries

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-connecting-multiple-backends-same-type

This is an example of how to execute GraphQL queries against the configured API Connect endpoint. It demonstrates fetching customer data by city and by ID from potentially different backends.

```graphql
query MyQuery {
  customersByCity(city: "Boston") {
    email
    name
  }
  customerById(id: "101") {
    email
    name
  }
}
```

--------------------------------

### Get ImageContentSourcePolicy in OpenShift

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Retrieves the `ImageContentSourcePolicy` resources from an OpenShift cluster to verify their creation and configuration.

```shell
oc get imageContentSourcePolicy
```

--------------------------------

### Get PostgreSQL Connection Info

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=ngrok-using-postgresql

Retrieves connection information for the PostgreSQL server, specifically the port number it is listening on. This is crucial for ngrok configuration.

```sql
psql postgres=# \conninfo
```

--------------------------------

### Create Project Workspace

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=apis-tutorial-create-graphql-api-graphql-backend

These commands set up a new directory for your GraphQL project and navigate into it. This is the initial step before importing any GraphQL schemas.

```bash
mkdir graphql-tutorial
cd graphql-tutorial
```

--------------------------------

### Create Project Workspace and Navigate

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=apis-tutorial-create-graphql-api-postgresql-database

These commands set up a new directory for your project and navigate into it, preparing the environment for the API Connect for GraphQL CLI commands.

```bash
mkdir postgresql-tutorial
cd postgresql-tutorial
```

--------------------------------

### Configure API Connect for GraphQL Installation (YAML)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-portable-computer-storage-device

Example custom resource (CR) file for installing API Connect for GraphQL. It includes minimal configurations like accepting the license, specifying image pull secrets, and setting up control database secrets. This snippet also demonstrates the configuration of horizontal pod autoscaling (HPA) for both graph and graph subscription services.

```yaml
apiVersion: stepzen-graph.ibm.com/v1beta1
kind: StepZenGraphServer
metadata:
  name: stepzen
spec:
  license:
    accept: true
  controlDatabaseSecret: db-secret
  imagePullSecrets: 
    - ibm-entitlement-key
  graphServer:
    hpa:
      minReplicas: 1
      maxReplicas: 10
      targetCPUUtilizationPercentage: 80
  graphServerSubscription:
    hpa:
      minReplicas: 1
      maxReplicas: 5
      targetCPUUtilizationPercentage: 80

```

--------------------------------

### Failed to Fetch Response Example

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=schemas-resolving-common-errors

This response indicates that the API Connect for GraphQL endpoint is unavailable. Verify that the `stepzen start` command is running to ensure the endpoint is active.

```json
{
  "message": "Failed to fetch",
  "stack": "TypeError: Failed to fetch"
}
```

--------------------------------

### GraphQL Playground Setup

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=basics-graphql-queries

Instructions for setting up GraphQL Playground to interact with the GitHub GraphQL API, including adding the endpoint and authorization header.

```APIDOC
## GraphQL Playground Setup

### Description
This section details the steps to configure GraphQL Playground for using the GitHub GraphQL API.

### API Endpoint
`https://api.github.com/graphql`

### Authentication
To authenticate, add an `Authorization` header with your Personal Access Token (PAT).

#### Request Body (Header Example)
```json
{
  "Authorization": "Bearer MY_TOKEN"
}
```

### Usage
1. Add the API endpoint to your GraphQL Playground.
2. Add the `Authorization` header with your token.
3. Explore the API schema via the 'Docs' tab.
```

--------------------------------

### GraphQL API - Conditional Routing using JSONATA

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-directive-supplies

This example demonstrates conditional resolution of a supplying field (`delivery`) using JSONATA to check if the `trackingId` argument starts with 'TYD-'.

```APIDOC
## GraphQL API - Conditional Routing using JSONATA

### Description
This query endpoint `tyd` resolves the `delivery` field only if the `trackingId` argument matches the regex /^TYD-/, using JSONATA for the condition, and integrates with a REST endpoint.

### Method
Not Applicable (GraphQL Schema Definition)

### Endpoint
Not Applicable (GraphQL Schema Definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```graphql
{
  tyd(trackingId: "TYD-ABCDE") {
    # Fields to query...
  }
}
```

### Response
#### Success Response (200)
- **tyd** (ToYourDoor) - The resolved ToYourDoor object if the condition is met.

#### Response Example
```json
{
  "data": {
    "tyd": {
      "trackingNumber": "TYD-ABCDE",
      "estimatedDelivery": "2023-10-28"
    }
  }
}
```
```

--------------------------------

### Create Workspace and Navigate Directory (Shell)

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=apis-tutorial-create-graphql-api-mysql-database

These commands are used to create a new directory for your project and then navigate into it, preparing your environment for the StepZen import process. No external dependencies are required.

```shell
mkdir mysql-tutorial
cd mysql-tutorial
```

--------------------------------

### Setting HTTP Method with @rest Directive (GraphQL Schema)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-connecting-rest-service

Illustrates how to specify the HTTP method for a request using the 'method' argument in the @rest directive. This example changes the default GET method to POST. Supported methods include DELETE, GET, PATCH, POST, and PUT. POST, PUT, and PATCH methods can utilize the 'postbody' argument.

```graphql
type Query {
  anything(message: String): JSON
  @rest (
    endpoint: "https://httpbin.org/anything"
    method: POST
    headers: [
      {name: "User-Agent", value: "Essentials"}
      {name: "X-Api-Key", value: "12345"}
    ]
    )
}
```

--------------------------------

### Create Project Structure

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-connecting-graphql-backend

Creates a new project directory named 'rick-and-morty' with a subdirectory 'schema' for GraphQL type definitions. This is the initial setup step for the API Connect project.

```shell
mkdir -p rick-and-morty/schema
cd rick-and-morty
```

--------------------------------

### Expose Fields with StepZen VisibilityPattern

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=types-input-stepzen-visibilitypattern

Example demonstrating how to expose specific fields within the 'Query' type that start with a lowercase letter. This utilizes the `expose:true` argument and regular expressions for field and type matching.

```graphql
{expose:true types:"Query" fields:"[a-z].*"}
```

--------------------------------

### Create Workspace Directory

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=apis-tutorial-create-graphql-api-mysql-database

Command to create a new directory for your project workspace. This is the initial step before setting up the API.

```bash
mkdir mysql-tutorial
```

--------------------------------

### Manipulate HTTP Request and Response Bodies with ECMAScript

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-custom-reference

This example illustrates the use of ECMAScript in GraphQL to modify both HTTP request and response bodies. The `bodyPOST` function alters the request payload, and `transformREST` modifies the response, both using a 'message' argument retrieved via the `get` function.

```graphql
type Query {
  scriptExample(message: String!): JSON
  @rest(
    endpoint: "https://httpbin.org/anything"
    method: POST
    ecmascript: """
      function bodyPOST(s) {
        let body = JSON.parse(s);
        body.ExtraMessage = get("message");
        return JSON.stringify(body);
      }

      function transformREST(s) {
        let out = JSON.parse(s);
        out.CustomMessage = get("message");
        return JSON.stringify(out);
      }
    """
  )
}
```

--------------------------------

### Configure PAGE_NUMBER Pagination in GraphQL with @rest Directive

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=service-paginating-rest-api-as-data-source

This example demonstrates configuring the PAGE_NUMBER pagination type for a GraphQL endpoint using the `@rest` directive in API Connect. It specifies how to set the total number of pages and defines arguments for the starting page and number of results per page.

```graphql
type User {
    id: ID!
    email: String!
    ...
  }

type UserEdge {
  node: User
  cursor: String
}

type UserConnection {
  pageInfo: PageInfo!
  edges: [UserEdge]
}

  ...

type Query {
  user(id: ID!): User
    @rest(endpoint: "https://reqres.in/api/users/$id", resultroot: "data")
  users(first: Int! = 6, after: String! = ""): UserConnection
    @rest(
      endpoint: "https://reqres.in/api/users?page=$after&per_page=$first"
      resultroot: "data[]"
      pagination: {
        type: PAGE_NUMBER
        setters: [{ field: "total", path: "total_pages" }]
      }
    )
}
```

--------------------------------

### Create MySQL Database and User

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-mysql

SQL commands to create a new database named 'tutorialdb', a user 'tutorialuser' with a password, and grant all privileges on the database to this user.

```sql
mysql> create database tutorialdb;
Query OK, 1 row affected (0.00 sec)

mysql> create user 'tutorialuser'@'localhost' identified by 'tutorialuserpassword';
Query OK, 0 rows affected (0.01 sec)

mysql> grant all on tutorialdb.* to 'tutorialuser'@'localhost';
Query OK, 0 rows affected (0.01 sec)
```

--------------------------------

### GET /anything/users/{id} (POST with custom body)

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=directives-connecting-rest-service

This example demonstrates how to use the @rest directive to define a GraphQL query that makes a POST request to a REST endpoint. It shows how to use variables in the endpoint URL and the request body.

```APIDOC
## POST /anything/users/{id}

### Description
This endpoint fetches data from an external REST service. It uses the `id` from the GraphQL query to construct the request URL and includes `name` and `message` in the POST request body using GoLang templating.

### Method
POST

### Endpoint
`https://httpbin.org/anything/users/$id`

### Parameters
#### Path Parameters
- **id** (ID) - Required - The ID of the user to fetch.

#### Query Parameters
- **name** (String) - Optional - The name of the user to include in the request body.
- **message** (String) - Optional - A message from the user to include in the request body.

#### Request Body
- **user.name** (String) - Optional - The name field within the user object.
- **user.message** (String) - Optional - The message field within the user object.

### Request Example
```json
{
  "user": {
    "name": "John Doe",
    "message": "Hello from GraphQL"
  }
}
```

### Response
#### Success Response (200)
- **JSON** - The response from the external REST service, often echoing the request details.

#### Response Example
```json
{
  "args": {},
  "data": "{\"user\": {\"name\": \"John Doe\", \"message\": \"Hello from GraphQL\"}}",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Content-Length": "57",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "Essentials",
    "X-Api-Key": "12345"
  },
  "json": {
    "user": {
      "message": "Hello from GraphQL",
      "name": "John Doe"
    }
  },
  "origin": "192.168.1.1",
  "url": "https://httpbin.org/anything/users/123"
}
```
```

--------------------------------

### Configure StepZen GraphQL Server Custom Resource (CR)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=graphql-installing-api-connect

This YAML defines the configuration for the StepZen GraphQL Server, including license acceptance, database secrets, image pull secrets, and horizontal pod autoscaling (HPA) settings for graph and subscription services. It's a minimal example to enable installation.

```yaml
apiVersion: stepzen-graph.ibm.com/v1beta1
kind: StepZenGraphServer
metadata:
  name: stepzen
spec:
  license:
    accept: true
  controlDatabaseSecret: db-secret
  imagePullSecrets: 
    - ibm-entitlement-key
  graphServer:
    hpa:
      minReplicas: 1
      maxReplicas: 10
      targetCPUUtilizationPercentage: 80
  graphServerSubscription:
    hpa:
      minReplicas: 1
      maxReplicas: 5
      targetCPUUtilizationPercentage: 80
```

--------------------------------

### Verify PostgreSQL Installation

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=ngrok-using-postgresql

Checks the installed version of PostgreSQL. This command confirms that the installation was successful.

```shell
psql --version
```

--------------------------------

### StepZen CLI Deployment Command

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=apis-tutorial-create-graphql-api-graphql-backend

Use the `stepzen start` command to deploy your generated GraphQL schema to API Connect for GraphQL. This command initiates the deployment process, making your GraphQL API accessible.

```bash
stepzen start
```

--------------------------------

### Configuring Cache Policy with 'cachepolicy' in API Connect GraphQL

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-directive-rest

Details the 'cachepolicy' argument for defining caching strategies for REST requests. It specifies default policies based on the HTTP method (GET, POST, etc.) and for Query and Mutation fields, and provides examples of how to explicitly set the strategy.

```graphql
query getItems @rest(cachepolicy: { strategy: ON }) { ... }

mutation createItem @rest(cachepolicy: { strategy: OFF }) { ... }
```

--------------------------------

### Install Podman on RHEL 9

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Installs the Podman container management tool on Red Hat Enterprise Linux 9. Podman is a prerequisite for managing containers during the installation process.

```shell
yum install podman
```

--------------------------------

### Quick Setup: GraphQL API for MySQL Database

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-connecting-mysql-database

This command provides a streamlined way to generate a GraphQL API backed by a MySQL database. It is part of the IBM API Connect for GraphQL toolkit, simplifying the initial setup and integration process.

```bash
stepzen import mysql
```

--------------------------------

### Verify MySQL Installation

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=ngrok-using-mysql

This command checks the installed version of MySQL. It's used to confirm that the installation was successful and to note the version for potential compatibility checks.

```shell
mysql --version
```

--------------------------------

### Install MySQL using Homebrew

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=ngrok-using-mysql

This command installs the MySQL database system on macOS using the Homebrew package manager. Ensure Homebrew is installed and updated before running this command.

```shell
brew install mysql
```

--------------------------------

### API Deployment and Testing

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-connecting-soapxml-backend

Instructions on how to deploy the GraphQL API using StepZen and how to test the deployed endpoint using a command-line tool.

```APIDOC
## Deployment and Testing

### Deployment
1. Navigate to your StepZen workspace in the terminal.
2. Run the command: `stepzen start`
3. Follow the prompts to choose an API name (e.g., `api/prodding-seastar`).
4. A confirmation message will appear in the terminal upon successful deployment.

### Testing
Use a tool like `curl` to send a GraphQL query to your deployed endpoint.

#### cURL Command Example
```bash
"https://<your-account-name>.stepzen.net/api/prodding-seastar/__graphql" \
  --header "Authorization: Apikey $(stepzen whoami --apikey)" \
  --header "Content-Type: application/json" \
  --data '{"query": "{conversion (celsius: 20.0)}"}'
```

Replace `<your-account-name>` with your actual StepZen account name.
```

--------------------------------

### Get Graph Server Status using oc command

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=operator-status

This command retrieves the status of the API Connect for GraphQL Graph Server custom resource in YAML format. The output provides detailed information about the server's health, including its conditions and version information. Dependencies include having the OpenShift CLI (oc) installed and configured to access the cluster.

```bash
oc get graphserver -o yaml
```

--------------------------------

### Generate Skopeo Commands for Image Mirroring in Kubernetes

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Generates a series of `skopeo copy` commands to mirror product images from a source to a target registry for Native Kubernetes environments. The commands are generated by parsing an images mapping file.

```shell
cat ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt | awk -F'=' '{ print "skopeo copy --all docker://"$1" docker://"$2 }'
```

--------------------------------

### Install Skopeo on RHEL 9

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Installs the Skopeo container image management tool on Red Hat Enterprise Linux 9. Skopeo is used for managing container images in Native Kubernetes environments.

```shell
yum install skopeo
```

--------------------------------

### Initialize API Connect GraphQL Workspace

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=setting-up-your-environment

This command initializes a new workspace directory for building GraphQL APIs. It creates the necessary project structure for your artifacts. Ensure you are in the desired parent directory before running this command.

```bash
stepzen init
```

--------------------------------

### Example JWT Payload for Authentication

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=schemas-securing-endpoints

This is an example of a JWT payload that can be used for authentication. When used with JWT.io, it demonstrates the structure of data that can be included in a JWT, such as user identifiers and timestamps. This payload is a basic example and can be extended.

```json
{"user":"john.doe@example.com"}
```

--------------------------------

### Create Workspace Directory

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=apis-tutorial-create-graphql-api-graphql-backend

Command to create a new directory for your project workspace. This is the initial step for setting up a new GraphQL API project.

```bash
mkdir graphql-tutorial
```

--------------------------------

### Verify ibm-pak Plugin Installation (Native Kubernetes)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Confirms the installation of the IBM Catalog Management Plug-in for IBM Cloud Paks on a Native Kubernetes environment. This verifies that the `kubectl ibm-pak` command is accessible and functional.

```shell
kubectl ibm-pak --help
```

--------------------------------

### Create or Set Namespace on OpenShift/Kubernetes

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Commands to create a new project/namespace and switch the current context to it. Replace `<my-namespace>` with your desired namespace name. For OpenShift, `oc` commands are used; for Kubernetes, `kubectl` is used.

```shell
oc new-project <my-namespace>
oc project <my-namespace>
```

```shell
kubectl create namespace <my-namespace>
kubectl config set-context --current --namespace=<my-namespace>
```

--------------------------------

### Verify ibm-pak Plugin Installation (OCP)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

Confirms the installation of the IBM Catalog Management Plug-in for IBM Cloud Paks on a Red Hat OpenShift environment. This plugin is essential for managing product images and running commands against the cluster.

```shell
oc ibm-pak --help
```

--------------------------------

### Order Subgraph Example

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=directives-building-supergraph-by-stitching-results

An example schema for an Order subgraph, defining Order type and queries to fetch orders from a MySQL database.

```APIDOC
## Order Subgraph Schema

### Description
Defines the `Order` type and queries to fetch order data, likely from a MySQL database.

### Type Definitions
```graphql
type Order {
  createOn: Date
  amount: Float
}
```

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

--------------------------------

### Customer Subgraph Example

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=directives-building-supergraph-by-stitching-results

An example schema for a Customer subgraph, defining Customer type and associated queries using @rest directive.

```APIDOC
## Customer Subgraph Schema

### Description
Defines the `Customer` type and queries to fetch customer data, potentially from a REST backend.

### Type Definitions
```graphql
type Customer {
  name: String
  id: ID
  email: String
}
```

### Query Definitions
```graphql
type Query {
  customer(id: ID): Customer @rest(endpoint: "https://api.acme.com/customers/$id")

  customerByEmail(email: String): Customer
    @rest(endpoint: "https://api.acme.com/customers?email=$email")
}
```
```

--------------------------------

### Example Login for API Connect for GraphQL CLI (EU Central)

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=setting-up-your-environment

An example of the login command for the API Connect for GraphQL CLI, specifying an account name 'beaverdam' and a domain in the 'eu-central-a' region.

```bash
stepzen login envname.eu-central-a.ibm.stepzen.net -a beaverdam
```

--------------------------------

### Create and Set OpenShift Project (Namespace)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-portable-computer-storage-device

These commands create a new project (namespace) in Red Hat OpenShift and then set the current context to that new project. Replace `<my-namespace>` with your desired namespace name.

--------------------------------

### Verify API Connect for GraphQL Deployment Status (Shell)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-portable-computer-storage-device

Command to check the status of the `StepZenGraphServer` resource in your cluster. This helps verify if the API Connect for GraphQL Software has been successfully installed and if the services are ready.

```bash
oc get StepZenGraphServer 

```

--------------------------------

### Install ngrok using Homebrew

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=locally-testing-ngrok

Installs the ngrok tool on macOS using the Homebrew package manager. This is a prerequisite for local API testing with ngrok.

```bash
brew cask install ngrok
```

--------------------------------

### stepzen help

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=schemas-cli-command-reference

Displays help information for the API Connect for GraphQL CLI commands. You can get general help or specific help for a particular command.

```APIDOC
## GET /websites/ibm_en_api-connect-graphql/cli/help

### Description
Displays help for the API Connect for GraphQL CLI. You can specify a command to get detailed help for it.

### Method
GET

### Endpoint
`/websites/ibm_en_api-connect-graphql/cli/help`

### Parameters
#### Query Parameters
- **command** (string) - Optional - The name of the command for which to display help (e.g., `login`). If omitted, general CLI help is provided.

### Request Example
General help:
```json
{
  "command": "stepzen help"
}
```

Specific command help:
```json
{
  "command": "stepzen help login"
}
```

### Response
#### Success Response (200)
- **help_text** (string) - The help documentation for the specified command or general CLI help.

#### Response Example
```json
{
  "help_text": "Usage: stepzen deploy [<endpoint>] [--config=<config>] [--dir=<dir>]\n\nDeploy a GraphQL API or schema to the API Connect for GraphQL server... (full help text would be here)"
}
```
```

--------------------------------

### GraphQL Tool Example

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=directives-directive-tool

This example defines a GraphQL tool named `customer-lookup` that exposes only the `Query.customer` field from the schema. The tool's description is templated.

```APIDOC
## GraphQL Tool Example

### Description
This configuration defines a GraphQL tool named `customer-lookup` which provides access to the `Query.customer` field. The tool description uses a template variable `{graphql_tool}`.

### Tool Definition
```
extend schema
  @tool(
    name: "customer-lookup"
    description: "Customer lookup tool. {graphql_tool}"
    graphql: {expose: true, types: "Query", fields: "customer"}
  )
```

### Parameters
- `name`: `customer-lookup`
- `description`: `Customer lookup tool. {graphql_tool}`
- `graphql`: Exposes `Query.customer`.

### Execution
This tool can be executed via the MCP method `tools/call` with parameters for a GraphQL request (query, operationName, variables).
```

--------------------------------

### Generate Mirror Manifests (Bash)

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-bastion-host

These commands generate the necessary manifest files for mirroring images. The command structure varies for Red Hat OpenShift (`oc ibm-pak`) and Native Kubernetes (`kubectl ibm-pak`), both requiring the CASE name, version, and target registry.

```bash
# For Red Hat OpenShift envt:
oc ibm-pak generate mirror-manifests $CASE_NAME --version $CASE_VERSION $TARGET_REGISTRY

# For Native Kubernetes envt:
kubectl ibm-pak generate mirror-manifests $CASE_NAME --version $CASE_VERSION $TARGET_REGISTRY
```

--------------------------------

### GraphQL GET Request with REST Endpoint

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-directive-rest

Defines a GraphQL query field 'get' that maps to a REST GET request. Arguments 'a' (Int) and 'b' (String) are automatically appended as URL query parameters to the specified endpoint. The response structure is defined by the 'Response' type.

```graphql
type Query {
  get(a: Int, b: String): Response @rest(endpoint: "https://httpbingo.org/get")
}
type Response {
  method: String
  origin: String
  url: String
  args: JSON
}
```

--------------------------------

### Login to MySQL as New User

Source: https://www.ibm.com/docs/en/api-connect-graphql/saas_topic=ngrok-using-mysql

This command logs into the MySQL server using the newly created 'tutorialuser' and 'tutorialdb' database. You will be prompted to enter the password for 'tutorialuser'.

```shell
desktop % mysql -u tutorialuser -p tutorialdb
Enter password: ************ // tutorialuserpassword
```

--------------------------------

### GraphQL Mutation Example for Optional User Update

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=directives-custom-reference

This is an example GraphQL mutation call to `updateUser_Optionals`, demonstrating how to provide `first_name` and `last_name` values for patching user information.

```graphql
mutation stepzenPatch {
  updateUser_Optionals(first_name: "John", last_name: "Doe")
}
```

--------------------------------

### Log in to ICR Registry using Podman

Source: https://www.ibm.com/docs/en/api-connect-graphql/1.1_topic=installation-installing-portable-computer-storage-device

Authenticates with the `cp.icr.io` registry using Podman. Requires `cp` as the username and an entitlement key as the password.

```bash
podman login cp.icr.io
```
Tokens:
Raw