Merge branch 'main' into mkall-field-access

Author: ddebrunner

README.md

@@ -27,93 +27,49 @@
 - [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)
 
-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/pagination/operations.graphql

@@ -1,5 +1,5 @@
 # Page through customers from a database connection based pagination
-query Customers($first: Int!, $after: String = "") {    
+query Customers($first: Int!, $after: String = "") {
   customers(first: $first, after: $after) {
     edges {
       node {

dbquery/pagination/tests/Test.js

@@ -2,7 +2,7 @@ const fs = require("fs");
 const path = require("node:path");
 const {
   deployAndRun,
-  authTypes,
+  stepzen,
   getTestDescription,
 } = require("../../../tests/gqltest.js");
 
@@ -44,7 +44,6 @@ describe(testDescription, function () {
           }
         }
       },
-      authType: authTypes.adminKey,
     },
     {
       label: "next set of results",
@@ -76,8 +75,7 @@ describe(testDescription, function () {
           }
         }
       },
-      authType: authTypes.adminKey,
     },
   ];
-  return deployAndRun(__dirname, tests);
+  return deployAndRun(__dirname, tests, stepzen.admin);
 });

dbquery/pings/postgresql/tests/Test.js

@@ -1,6 +1,5 @@
 const {
   deployAndRun,
-  authTypes,
   getTestDescription,
 } = require("../../../../tests/gqltest.js");
 

executable/persisted/tests/Test.js

@@ -3,7 +3,7 @@ const path = require("node:path");
 
 const {
   deployAndRun,
-  authTypes,
+  stepzen,
   getTestDescription,
 } = require("../../../tests/gqltest.js");
 
@@ -27,7 +27,6 @@ describe(testDescription, function () {
           name: "Tromp",
         },
       },
-      authType: authTypes.adminKey,
     },
     {
       label: "CustomerName",
@@ -42,7 +41,6 @@ describe(testDescription, function () {
           email: "[email protected]",
         },
       },
-      authType: authTypes.adminKey,
     },
     {
       label: "Customer",
@@ -64,8 +62,7 @@ describe(testDescription, function () {
           },
         },
       },
-      authType: authTypes.adminKey,
     },
   ];
-  return deployAndRun(__dirname, tests);
+  return deployAndRun(__dirname, tests,stepzen.admin);
 });

materializer/nestedfieldselection/api.graphql

@@ -1,11 +1,11 @@
 # See preamble in README.md
 
 type Document {
-   docId: String
-   content(id: String!): Content
-     @materializer(query: "content", arguments:[{name: "id" argument:"id"}])
-   author: Author 
-   lastUpdate: Date
+  docId: String
+  content(id: String!): Content
+    @materializer(query: "content", arguments: [{ name: "id", argument: "id" }])
+  author: Author
+  lastUpdate: Date
 }
 
 type Content @mock {
@@ -15,36 +15,47 @@ type Content @mock {
 }
 
 type Query {
-  document:  Document
-       @rest(
-       endpoint: "stepzen:empty"
-       transforms: [{
-        editor: """jq: {"author": { "name":"Roy Derks", "country":"Netherlands"}}"""
-       }]
-       )
-  # Content is exposed here to keep the snippet self-contained, but would otherwise not be exposed as an operation   
-  content(id: String!): Content 
-      @connector(type:"echo")
+  document: Document
+    @rest(
+      endpoint: "stepzen:empty"
+      transforms: [
+        {
+          editor: """
+          jq: {"author": { "name":"Roy Derks", "country":"Netherlands"}}
+          """
+        }
+      ]
+    )
+  # Content is exposed here to keep the snippet self-contained, but would otherwise not be exposed as an operation
+  content(id: String!): Content @connector(type: "echo")
 }
 
 type Author {
-    name: String!
-    country: String
+  name: String!
+  country: String
 }
 
 type Query {
   book: Book
     @rest(
-       endpoint: "stepzen:empty"
-       transforms: [{
-        editor: """jq: {"refId": "27", "name": "Fullstack GraphQL"}"""
-       }]
+      endpoint: "stepzen:empty"
+      transforms: [
+        {
+          editor: """
+          jq: {"refId": "27", "name": "Fullstack GraphQL"}
+          """
+        }
+      ]
     )
 }
 
 type Book {
   refId: String!
   name: String
-  author: Author @materializer (query: "document {author}")
-  content: Content @materializer (query: "document {content}", arguments: {name: "id", field: "refId"})
-} 
+  author: Author @materializer(query: "document {author}")
+  content: Content
+    @materializer(
+      query: "document {content}"
+      arguments: { name: "id", field: "refId" }
+    )
+}

materializer/nestedfieldselection/index.graphql

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

materializer/nestedfieldselection/tests/Test.js

@@ -1,6 +1,6 @@
 const {
   deployAndRun,
-  authTypes,
+  stepzen,
   getTestDescription,
 } = require("../../../tests/gqltest.js");
 
@@ -24,8 +24,7 @@ describe(testDescription, function () {
             }
           }
         },
-      authType: authTypes.adminKey,
     },
   ]
-  return deployAndRun(__dirname, tests);
+  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_!