Merge branch 'main' into jwt-claim-pagination

Author: ddebrunner

README.md

@@ -27,93 +27,51 @@
 - [Explore the docs](https://stepzen.com/docs)
 - [View Demo](https://stepzen.com/developers/videos/graph-of-graphs)
 - [Report Bug](https://github.com/stepzen-dev/snippets/issues)
-- [Request Snippet](https://github.com/stepzen-dev/issues)
+- [Request Snippet](https://github.com/stepzen-dev/snippets/issues)
 - [Join our Discord Server](https://discord.com/invite/9k2VdPn2FR)
   </p>
 </div>
 
-<!-- TABLE OF CONTENTS -->
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li>
-      <a href="#about-the-project">About The Project</a>
-    </li>
-    <li><a href="#transforms">`@transforms`</a></li>
-    <li><a href="#sequence">`@sequence`</a></li>
-    <li><a href="#protection">protection</a></li>
-    <li><a href="#rest-calls-and-responses">`@rest` calls and responses</a></li>
-
-  </ol>
-</details>
-
 ## About the project
 
-This repo contains `.graphql` (and in some case, `config.yaml` files) for various "self-contained" example code for doing operations in StepZen.
+Code snippets that demonstrate use of custom directives and other techniques in
+IBM API Connect Essentials (StepZen).
 
 ## Getting Started
 
-[Install](https://stepzen.com/docs/quick-start/install-and-setup) the StepZen command line interface.
-
-To run these examples,
-
-- `git clone` this repo
-- Change to the right working directory.
-- run `stepzen start`
-
-## transforms
-
-For more on what `transforms` is and how it operates within the custom `@rest` directive, [see our documentation](https://stepzen.com/docs/custom-graphql-directives/directives#transforms).
-
-These are available in `/transforms`:
-
-- `/filter` shows how the response of a REST API can be filtered
-- `/combineintostring` shows how a new field in the return type can be created by concatenating some other fields (like address parts into one address)
-- `/jsonobjectToJsonarray` shows how an array of data (say coords) can be converted into an object, `{"lat":, "lon",..}` so that it can be fed into some other system that requires data to be expressed that way
-- `/jsonobjectToJsonarray` shows how an object (typically where each key is an id of a record) can be converted into an array (e.g., `{"1":{"name": "john"}, "2": "jane"}` can be converted to `[{"id":"1", "name": "john"}, {"id":"2", name: "jane"}]`), so that it can then behave well for GraphQL processing.
-
-## @sequence
-
-View the StepZen [documentation](https://stepzen.com/docs/custom-graphql-directives/directives#-sequence) on the custom directive `@sequence`.
-
-These are available in `/sequence`:
-
-- `/arguments` shows how query arguments get passed down a sequence
-- `/forLoops` shows how sequence acts as a nested for loop
-- `/transformsInMaterializer` shows how connecting two subgraphs can invoke transformations in between. For example, the `city` of a customer can be fed into a `weather` that takes `lat,lon` by calling some geocoding in the sequence
-- `/useOfJSON` shows how, in long sequences, a new type does not have to created for every step--treat everything as JSON up to the last step, and your type system stays clean.
-
-## @dbquery
-
-View the documentation for the [`@dbquery` custom directive](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-dbquery) in the documentation.
-
-Uses a database filled with mock data.
-
-- `/pagination` shows how to implement connection model pagination for a database.
-
-## protection
+Sign up for a free API Connect Essentials SaaS plan: https://www.ibm.com/account/reg/us-en/signup?formid=urx-52542
 
-For more information on protecting your API, [see our documentation](https://stepzen.com/docs/access-control).
+Read: [understanding API Connect Essentials (StepZen)](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=understanding-api-connect-essentials)
 
-In `/protection`, you will find several subdirectories. Each contains a `.graphql` file, and `index.graphql` file and a `config.yaml` settings (which enables you to get extremely granular (or coarse) with protecting who can call what query/mutation).
+[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment#set-up-env__title__3) the StepZen command line interface.
 
-- `/makeAllPublic` shows how you can easily make all queries public.
-- `/makeSomePublic` shows how you can make some public, and some private (which can still be accessed using your `admin` or `service` keys)
+Documentation: https://www.ibm.com/docs/en/api-connect/ace/saas
 
-## @rest calls and responses
+## Snippets
 
-Where possible, we use [httpbingo.org](https://httpbingo.org) as our REST endpoint, since it allows us to mimic lots of REST capabilities.
+The snippets are generally broken up into functional areas, with each folder covering a specific topic:
 
-- `/restWithParameters` shows how GraphQL query arguments are automatically added to the REST call--there is nothing for you to do!
-- `/restWithConfigYaml` shows how REST query parameters can also be fetched from `config.yaml`--this allows you to keep your SDL code separate from your secrets.
-- `/postbody` shows how a POST body can be automatically filled with query arguments when the `Content-Type:application/x-www-form-urlencoded`. This is the easiest way to send postbodies down the REST API
-- `/morecomplexpost` shows how a POST body can be filled with query arguments using `{{.Get \"name-of-query-argument\"}}` when the `Content-Type:application/x-www-form-urlencoded`.
+### Custom Directives
 
-## union types
+- [@dbquery](dbquery/README.md) - Use `@dbquery` for connecting to databases, including pagination and filtering.
+- [@materializer](materializer) - Use of `@materializer` to extend types by linking disparate backends into a single unified view.
+- @rest - Connects to REST APIs
+  - [rest](rest/README.md) - Use of `@rest` for connecting to REST endpoints, including pagination.
+  - [transforms](transforms/README.md) - How to transform REST API responses to match GraphQL types with `@rest`.
+- [@sequence](sequence/README.md) - Use of `@sequence` to resolve a field from multiple field resolutions, such as multiple backend calls.
+- @sdl
+  - [executable](executable) - How GraphQL _executable documents_ can be registered and used with a schema or endpoint.
+- @supplies
+  - [routing](routing)
+- @value
+  - [value](value)
 
-Union types are valuable when you have a field that can return one of several types.
+### General topics
 
-- `/errorsAsData` shows how to implement the "errors as data" pattern. This is useful when you want to return a field that can return either a value or an error.
+- [pocs](pocs) - Techniques that can be used during development of proof of concepts with StepZen.
+- [protection](protection/README.md) - How to protect or expose GraphQL endpoints including field based access rules.
+- [reshape](reshape/README.md) - How to reshape GraphQL schema elements.
+- [unions](unions/README.md) - Uses of the GraphQL `union` type.
 
 <!-- MARKDOWN LINKS & IMAGES -->
 <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

dbquery/README.md

@@ -0,0 +1,12 @@
+# @dbquery
+
+The custom directive `@dbquery` allows easy declarative inclusion of a database backend in a GraphQL schema.
+
+GraphQL pagination and filtering are easily supported.
+
+View the documentation for the [`@dbquery` custom directive](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-dbquery) in the documentation.
+
+Uses a database filled with mock data.
+
+- [pagination](pagination) shows how to implement connection model pagination for a database.
+- [pings](pings) has snippets that can be deployed to see if connectivity to a database is setup correctly.

dbquery/custom-query/README.md

@@ -0,0 +1,65 @@
+
+# SQL Queries with `@dbquery`
+
+This snippet demonstrates how to configure the `@dbquery` directive for custom SQL queries.
+
+## Getting Started
+
+[Install](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=setting-up-your-environment) the StepZen command line interface.
+
+To run these examples,
+
+- `git clone` this repo
+- Change to the right working directory.
+- run `stepzen deploy`
+
+This example uses a demo database filled with mock data, you can inspect the `config.yaml` file to find the credentials for this database. Also you can configure the connection in the `config.yaml` file by providing your database credentials.
+
+Here’s a more generalized and specific description of the `@dbquery` directive functionality without referring to any particular data:
+
+---
+
+## The `@dbquery` Directive with SQL Query
+
+The `@dbquery` directive in StepZen is used to connect your GraphQL API to databases and allows you to execute custom SQL queries within your schema. It supports various database types, such as MySQL, PostgreSQL, MSSQL, and Snowflake.
+
+In this snippet, the `query` argument is used to define custom SQL queries for more control over the data being fetched. The functionality of the `query` argument allows for:
+
+- Running complex SQL queries directly from GraphQL fields.
+- Retrieving data from specific columns or joining multiple tables based on your query requirements.
+- Filtering and querying data using SQL syntax when database field names or structures differ from the GraphQL schema.
+
+The `query` argument provides the flexibility to write any SQL statement, while the **configuration** argument references the connection settings defined in the `config.yaml` file.
+
+For example, a query may look like this:
+
+```graphql
+@dbquery(
+  query: "SELECT column1, column2 FROM your_table WHERE condition = $1",
+  type: "postgresql",
+  configuration: "your_config"
+)
+```
+
+This allows you to fetch exactly the data you need, based on the custom SQL query provided. You can adjust the queries to match your database schema and use case.
+
+## Try it Out!
+
+Deploy the schema from `dbquery/custom-query` relative to the repository's root directory:
+
+```
+stepzen deploy
+```
+
+Run the [sample operations](operations.graphql):
+
+- **Fetch all customers**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customers
+  ```
+
+- **Fetch a customer by ID**:
+  ```
+  stepzen request -f operations.graphql --operation-name=Customer --var id=1
+  ```
+  

dbquery/custom-query/api.graphql

@@ -0,0 +1,71 @@
+# This example shows how @dbquery is configured for custom SQL queries with Customer data.
+
+"""
+Represents a customer in the system, stored in the 'customer' table of a PostgreSQL database.
+Each customer has an ID, name, and email. The 'Customer' type maps directly to the
+corresponding table fields.
+"""
+type Customer {
+    id: ID!
+    name: String
+    email: String
+}
+
+"""
+Defines the root-level queries for fetching customer data.
+These queries use the `@dbquery` directive to execute custom SQL queries.
+The SQL queries include parameter markers, which correspond to the GraphQL field arguments.
+
+The 'customer' table in PostgreSQL has the following structure:
+
+  CREATE TABLE customer (
+    id SERIAL PRIMARY KEY,          -- Unique identifier with sequence
+    name CHARACTER(50) NOT NULL,    -- Customer's name, max 50 characters
+    email CHARACTER(50) NOT NULL,   -- Customer's email, max 50 characters, must be unique
+    CONSTRAINT customer_email_key UNIQUE (email)  -- Unique constraint on email
+  );
+These queries demonstrate basic SQL interactions with this table.
+"""
+type Query {
+    """
+    Fetches a list of all customers from the database.
+
+    The custom SQL query retrieves the `id`, `name`, and `email` fields from the 'customer' table.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, it fetches all records from the 'customer' table.
+    - `type`: Specifies the type of database being queried. In this case, it’s a PostgreSQL database.
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This field does not take any arguments, and hence there are no parameter markers in the SQL query.
+    The SQL query is static, always returning all customers from the database.
+    """
+    customers: [Customer]
+        @dbquery(
+            query: "SELECT id, name, email FROM customer"
+            type: "postgresql"
+            configuration: "postgresql_config"
+        )
+
+    """
+    Fetches a single customer by their ID from the database.
+
+    **Field Argument to Parameter Marker Mapping**:
+    - Maps the `id` argument to the `$1` marker in the SQL query, allowing dynamic ID-based retrieval.
+    - `$1` serves as a placeholder, which will be replaced by the provided `id` value during execution.
+
+    **@dbquery Directive Usage**:
+    - `query`: This is the SQL query that will be executed. Here, the customer data is fetched based on the provided `id` value.
+      - The `$1` marker is a placeholder for the value of the `id` argument, which is passed as a variable when executing the query.
+    - `type`: Specifies the type of database being queried (PostgreSQL).
+    - `configuration`: References the database configuration (connection details) in StepZen.
+
+    This field requires an `id` argument as input, which is passed as a variable from the GraphQL request. The variable's value is used to fetch the corresponding customer from the database.
+    """
+    customer(id: Int!): Customer
+        @dbquery(
+            query: "SELECT id, name, email FROM customer WHERE id = $1"
+            type: "postgresql"
+            configuration: "postgresql_config"
+        )
+}

dbquery/custom-query/config.yaml

@@ -0,0 +1,4 @@
+configurationset:
+  - configuration:
+      name: postgresql_config
+      uri: postgresql://postgresql.introspection.stepzen.net/introspection?user=testUserIntrospection&password=HurricaneStartingSample1934

dbquery/custom-query/index.graphql

@@ -0,0 +1,3 @@
+schema @sdl(files: ["api.graphql"]) {
+  query: Query
+}

dbquery/custom-query/operations.graphql

@@ -0,0 +1,17 @@
+# Retrieve a specific customer by ID using a variable
+query Customer($id: Int!) {
+  customer(id: $id) {
+    id
+    name
+    email
+  }
+}
+
+# Retrieve all customers in the system
+query Customers {
+  customers {
+    id
+    name
+    email
+  }
+}

dbquery/custom-query/stepzen.config.json

@@ -0,0 +1,4 @@
+{
+    "endpoint": "api/miscellaneous"
+  }
+  

dbquery/custom-query/tests/Test.js

@@ -0,0 +1,57 @@
+const fs = require("fs");
+const path = require("node:path");
+const {
+  deployAndRun,
+  stepzen,
+  getTestDescription,
+} = require("../../../tests/gqltest.js");
+
+testDescription = getTestDescription("snippets", __dirname);
+
+// Read the GraphQL operations from the operations file
+const requestsFile = path.join(path.dirname(__dirname), "operations.graphql");
+const requests = fs.readFileSync(requestsFile, "utf8").toString();
+
+describe(testDescription, function () {
+
+  const tests = [
+    {
+      label: "fetch all customers",
+      query: requests,
+      operationName: "Customers",
+      variables: {},
+      expected: {
+        customers: [
+          { id: "1", name: "Lucas Bill                                        ", email: "[email protected]                            " },
+          { id: "2", name: "Mandy Jones                                       ", email: "[email protected]                           " },
+          { id: "3", name: "Salim Ali                                         ", email: "[email protected]                             " },
+          { id: "4", name: "Jane Xiu                                          ", email: "[email protected]                              " },
+          { id: "5", name: "John Doe                                          ", email: "[email protected]                              " },
+          { id: "6", name: "Jane Smith                                        ", email: "[email protected]                            " },
+          { id: "7", name: "Sandeep Bhushan                                   ", email: "[email protected]                       " },
+          { id: "8", name: "George Han                                        ", email: "[email protected]                            " },
+          { id: "9", name: "Asha Kumari                                       ", email: "[email protected]                           " },
+          { id: "10", name: "Salma Khan                                        ", email: "[email protected]                            " }
+        ]
+      },
+    },
+    {
+      label: "fetch customer by ID",
+      query: requests,
+      operationName: "Customer",
+      variables: { 
+        id: 1  
+      },
+      expected: {
+        customer: {
+          id: "1",
+          name: "Lucas Bill                                        ",
+          email: "[email protected]                            "
+        }
+      },
+    },
+  ];
+
+  // Run the tests against the deployed schema
+  return deployAndRun(__dirname, tests, stepzen.admin);
+});

pocs/README.md

@@ -0,0 +1,34 @@
+# Developing PoCs.
+
+## Sharing
+
+When developing a GraphQL PoC using IBM API Connect Essentials (StepZen) you will typically
+want to share the endpoint to allow others to evaluate it by making GraphQL requests against it.
+
+### Admin key
+
+> [!CAUTION]
+> Never share an endpoint by handing out the account's adminkey (`stepzen whoami --adminkey`).
+
+### API key
+
+The most simple (but somewhat risky) approach is to share the account's apikey (`stepzen whoami --apikey`).
+
+> [!WARNING]
+> The admin key grants access to all endpoints within an account. Thus if you are working on different PoCs, by providing access to one you provide access to all
+> which could leak information between different departments or clients.
+
+### Obfuscated endpoints
+
+Obfuscated endpoints allow sharing without handing out any keys or tokens.
+
+The concept can include single-use or short-lived endpoints for a demos, or time-limited evaluations.
+
+> [!WARNING]
+> Obfuscated endpoints are public, but have a hard to guess endpoint URL so anyone with the URL has access to the API.
+
+See [obfuscated-endpoint-url](obfuscated-endpoint-url/README.md)
+
+### JWT
+
+_Coming Soon_!