Skip to content

Commit 3b64b3b

Browse files
ddebrunnerddebrunner
authored
Cleanup the root readme and include all snippets folders. (#63)
* bring readmes up to date * chore: cleanup
1 parent dc3d900 commit 3b64b3b

File tree

7 files changed

+89
-69
lines changed

7 files changed

+89
-69
lines changed

‎README.md

Lines changed: 25 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -27,93 +27,49 @@
2727
- [Explore the docs](https://stepzen.com/docs)
2828
- [View Demo](https://stepzen.com/developers/videos/graph-of-graphs)
2929
- [Report Bug](https://github.com/stepzen-dev/snippets/issues)
30-
- [Request Snippet](https://github.com/stepzen-dev/issues)
30+
- [Request Snippet](https://github.com/stepzen-dev/snippets/issues)
3131
- [Join our Discord Server](https://discord.com/invite/9k2VdPn2FR)
3232
</p>
3333
</div>
3434

35-
<!-- TABLE OF CONTENTS -->
36-
<details>
37-
<summary>Table of Contents</summary>
38-
<ol>
39-
<li>
40-
<a href="#about-the-project">About The Project</a>
41-
</li>
42-
<li><a href="#transforms">`@transforms`</a></li>
43-
<li><a href="#sequence">`@sequence`</a></li>
44-
<li><a href="#protection">protection</a></li>
45-
<li><a href="#rest-calls-and-responses">`@rest` calls and responses</a></li>
46-
47-
</ol>
48-
</details>
49-
5035
## About the project
5136

52-
This repo contains `.graphql` (and in some case, `config.yaml` files) for various "self-contained" example code for doing operations in StepZen.
37+
This repo self-contained snippets that demonstrate use of custom directives and other techniques in
38+
IBM API Connect Essentials (StepZen).
5339

5440
## Getting Started
5541

56-
[Install](https://stepzen.com/docs/quick-start/install-and-setup) the StepZen command line interface.
57-
58-
To run these examples,
59-
60-
- `git clone` this repo
61-
- Change to the right working directory.
62-
- run `stepzen start`
63-
64-
## transforms
65-
66-
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).
67-
68-
These are available in `/transforms`:
69-
70-
- `/filter` shows how the response of a REST API can be filtered
71-
- `/combineintostring` shows how a new field in the return type can be created by concatenating some other fields (like address parts into one address)
72-
- `/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
73-
- `/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.
74-
75-
## @sequence
76-
77-
View the StepZen [documentation](https://stepzen.com/docs/custom-graphql-directives/directives#-sequence) on the custom directive `@sequence`.
78-
79-
These are available in `/sequence`:
80-
81-
- `/arguments` shows how query arguments get passed down a sequence
82-
- `/forLoops` shows how sequence acts as a nested for loop
83-
- `/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
84-
- `/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.
85-
86-
## @dbquery
87-
88-
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.
89-
90-
Uses a database filled with mock data.
91-
92-
- `/pagination` shows how to implement connection model pagination for a database.
93-
94-
## protection
42+
Sign up for a free API Connect Essentials SaaS plan: https://www.ibm.com/account/reg/us-en/signup?formid=urx-52542
9543

96-
For more information on protecting your API, [see our documentation](https://stepzen.com/docs/access-control).
44+
Read: [understanding API Connect Essentials (StepZen)](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=understanding-api-connect-essentials)
9745

98-
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).
46+
[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.
9947

100-
- `/makeAllPublic` shows how you can easily make all queries public.
101-
- `/makeSomePublic` shows how you can make some public, and some private (which can still be accessed using your `admin` or `service` keys)
48+
Documentation: https://www.ibm.com/docs/en/api-connect/ace/saas
10249

103-
## @rest calls and responses
50+
## Snippets
10451

105-
Where possible, we use [httpbingo.org](https://httpbingo.org) as our REST endpoint, since it allows us to mimic lots of REST capabilities.
52+
The snippets are generally broken up into functional areas, with each folder covering a specific topic:
10653

107-
- `/restWithParameters` shows how GraphQL query arguments are automatically added to the REST call--there is nothing for you to do!
108-
- `/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.
109-
- `/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
110-
- `/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`.
54+
### Custom Directives
11155

112-
## union types
56+
- [@dbquery](dbquery/README.md) - Use `@dbquery` for connecting to databases, including pagination and filtering.
57+
- [@materializer](materializer) - Use of `@materializer` to extend types by linking disparate backends into a single unified view.
58+
- @rest - Connects to REST APIs
59+
- [rest](rest/README.md) - Use of `@rest` for connecting to REST endpoints, including pagination.
60+
- [transforms](transforms/README.md) - How to transform REST API responses to match GraphQL types with `@rest`.
61+
- [@sequence](sequence/README.md) - Use of `@sequence` to resolve a field from multiple field resolutions, such as multiple backend calls.
62+
- @sdl
63+
- [executable](executable) - How GraphQL _executable documents_ can be registered and used with a schema or endpoint.
64+
- @supplies
65+
- [routing](routing)
11366

114-
Union types are valuable when you have a field that can return one of several types.
67+
### General topics
11568

116-
- `/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.
69+
- [pocs](pocs) - Techniques that can be used during development of proof of concepts with StepZen.
70+
- [protection](protection/README.md) - How to protect or expose GraphQL endpoints including field based access rules.
71+
- [reshape](reshape/README.md) - How to reshape GraphQL schema elements.
72+
- [unions](unions/README.md) - Uses of the GraphQL `union` type.
11773

11874
<!-- MARKDOWN LINKS & IMAGES -->
11975
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

‎dbquery/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# @dbquery
2+
3+
The custom directive `@dbquery` allows easy declarative inclusion of a database backend in a GraphQL schema.
4+
5+
GraphQL pagination and filtering are easily supported.
6+
7+
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.
8+
9+
Uses a database filled with mock data.
10+
11+
- [pagination](pagination) shows how to implement connection model pagination for a database.
12+
- [pings](pings) has snippets that can be deployed to see if connectivity to a database is setup correctly.

‎protection/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# protection
2+
3+
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).
4+
5+
- [jwt-claims](jwt-claims) shows how JWT claims can be used for field arguments.
6+
- [jwt-claims-dbquery](jwt-claims-dbquery) shows using JWT claims to control what can be accessed from a database.
7+
- [makeAllPublic](makeAllPublic) shows how you can easily make all `Query` fields public, thus resulting in a public endpoint.
8+
- [makeSomePublic](makeSomePublic) shows how you can make fields public, and some private (which can still be accessed using your `admin` or `service` keys).
9+
- [simpleABACSample](simpleABACSample) shows how to control access to fields using JWT claims.

‎rest/README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## @rest calls and responses
2+
3+
`@rest` is a powerful declarative custom directive that brings REST API calls into a GraphQL schema.
4+
5+
Documentation: https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-rest
6+
7+
Where possible, we use [httpbingo.org](https://httpbingo.org) as our REST endpoint, since it allows us to mimic lots of REST capabilities.
8+
9+
- [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`.
10+
- [pagination](pagination) shows how standard REST API pagination styles can be converted to standard GraphQL pagination.
11+
- [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
12+
- [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.
13+
- [restWithParameters](restWithParameters) shows how GraphQL field arguments are automatically added to the REST call--there is nothing for you to do!

‎sequence/README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# @sequence
2+
3+
The custom directive `@sequence` resolves a field by execute a sequence of other fields, for example, fetching an authorization token
4+
and then connecting to a backend.
5+
6+
View the [documentation](https://www.ibm.com/docs/en/api-connect/ace/saas?topic=directives-directive-sequence) on the custom directive `@sequence`.
7+
8+
## Snippets
9+
10+
- [arguments](arguments) shows how query arguments get passed down a sequence
11+
- [forLoops](forLoops) shows how sequence acts as a nested for loop
12+
- [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
13+
- [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.

‎transforms/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Transforms
2+
3+
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.
4+
5+
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).
6+
7+
## Snippets
8+
9+
- [filter](filter) shows how the response of a REST API can be filtered
10+
- [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)
11+
- [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
12+
- [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.

‎unions/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# union types
2+
3+
Union types are valuable when you have a field that can return one of several types.
4+
5+
- [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.

0 commit comments

Comments
 (0)