From 36627d15a1236ae58e1612ac775299aaa495a0de Mon Sep 17 00:00:00 2001 From: Dan Debrunner Date: Fri, 13 Sep 2024 09:58:40 -0400 Subject: [PATCH 1/2] bring readmes up to date --- README.md | 94 ++++++++++++-------------------------------- dbquery/README.md | 12 ++++++ protection/README.md | 9 +++++ rest/README.md | 13 ++++++ sequence/README.md | 13 ++++++ transforms/README.md | 12 ++++++ unions/README.md | 5 +++ 7 files changed, 89 insertions(+), 69 deletions(-) create mode 100644 dbquery/README.md create mode 100644 protection/README.md create mode 100644 rest/README.md create mode 100644 sequence/README.md create mode 100644 transforms/README.md create mode 100644 unions/README.md diff --git a/README.md b/README.md index 898cd7c..e294cdc 100644 --- a/README.md +++ b/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)

- -
- Table of Contents -
    -
  1. - About The Project -
    2. -
  2. `@transforms`
    3. -
  3. `@sequence`
    4. -
  4. protection
    5. -
  5. `@rest` calls and responses
    6. - -
-
- ## 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. +This repo self-contained snippets that demonstrate use of custom directives and other techniques in +IBM API Connect Essentuials (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: 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`. +### 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. diff --git a/dbquery/README.md b/dbquery/README.md new file mode 100644 index 0000000..879f6cb --- /dev/null +++ b/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. diff --git a/protection/README.md b/protection/README.md new file mode 100644 index 0000000..9bede8b --- /dev/null +++ b/protection/README.md @@ -0,0 +1,9 @@ +# protection + +For more information on protecting your API, [see our documentation](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=endpoints-using-jwt-based-access-control). + +- [jwt-claims](jwt-claims) shows how JWT claims can be used for field arguments. +- [jwt-claims-dbquery](jwt-claims-dbquery) shows using JWT claims to control what can be accessed from a database. +- [makeAllPublic](makeAllPublic) shows how you can easily make all `Query` fields public, thus resulting in a public endpoint. +- [makeSomePublic](makeSomePublic) shows how you can make fields public, and some private (which can still be accessed using your `admin` or `service` keys). +- [simpleABACSample](simpleABACSample) shows how to control access to fields using JWT claims. diff --git a/rest/README.md b/rest/README.md new file mode 100644 index 0000000..0f6ffa3 --- /dev/null +++ b/rest/README.md @@ -0,0 +1,13 @@ +## @rest calls and responses + +`@rest` is a powerful declarative custom directive that brings REST API calls into a GraphQL schema. + +Documentation: https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-rest + +Where possible, we use [httpbingo.org](https://httpbingo.org) as our REST endpoint, since it allows us to mimic lots of REST capabilities. + +- [morecomplexpost](morecomplexpost) shows how a POST body can be filled with field arguments using `{{.Get \"name-of-query-argument\"}}` when the `Content-Type:application/x-www-form-urlencoded`. +- [pagination](pagination) shows how standard REST API pagination styles can be converted to standard GraphQL pagination. +- [postbody](postbody) shows how a POST body can be automatically filled with field arguments with `Content-Type:application/x-www-form-urlencoded`. This is the easiest way to send postbodies down the REST API +- [restWithConfigYaml](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. +- [restWithParameters](restWithParameters) shows how GraphQL field arguments are automatically added to the REST call--there is nothing for you to do! diff --git a/sequence/README.md b/sequence/README.md new file mode 100644 index 0000000..53fb4f2 --- /dev/null +++ b/sequence/README.md @@ -0,0 +1,13 @@ +# @sequence + +The custom directive `@sequence` resolves a field by execute a sequence of other fields, for example, fetching an authorization token +and then connecting to a backend. + +View the [documentation](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-sequence) on the custom directive `@sequence`. + +## Snippets + +- [arguments](arguments) shows how query arguments get passed down a sequence +- [forLoops](forLoops) shows how sequence acts as a nested for loop +- [transformsInMaterializer](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](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. diff --git a/transforms/README.md b/transforms/README.md new file mode 100644 index 0000000..ec4f038 --- /dev/null +++ b/transforms/README.md @@ -0,0 +1,12 @@ +# Transforms + +When bringing a REST API into a schema using `@rest` the response may need to be transformed to align with the GraphQL type used the field's type. + +For more on what `transforms` is and how it operates within the custom `@rest` directive, [see our documentation](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-rest#transforms-transform__title__1). + +## Snippets + +- [filter](filter) shows how the response of a REST API can be filtered +- [combineintostring](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](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](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. diff --git a/unions/README.md b/unions/README.md new file mode 100644 index 0000000..000db87 --- /dev/null +++ b/unions/README.md @@ -0,0 +1,5 @@ +# union types + +Union types are valuable when you have a field that can return one of several types. + +- [errorsAsData](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. From ab68394aa082de71e34024acdbd4d0486ef43080 Mon Sep 17 00:00:00 2001 From: Dan Debrunner Date: Fri, 13 Sep 2024 10:04:26 -0400 Subject: [PATCH 2/2] chore: cleanup --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e294cdc..d82ab88 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,13 @@ ## About the project This repo self-contained snippets that demonstrate use of custom directives and other techniques in -IBM API Connect Essentuials (StepZen). +IBM API Connect Essentials (StepZen). ## Getting Started Sign up for a free API Connect Essentials SaaS plan: https://www.ibm.com/account/reg/us-en/signup?formid=urx-52542 -Read: https://www.ibm.com/docs/en/api-connect/ace/saas?topic=understanding-api-connect-essentials +Read: [understanding API Connect Essentials (StepZen)](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=understanding-api-connect-essentials) [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. @@ -51,11 +51,11 @@ Documentation: https://www.ibm.com/docs/en/api-connect/ace/saas The snippets are generally broken up into functional areas, with each folder covering a specific topic: -### Directives +### Custom Directives - [@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 - 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.