diff --git a/.github/linters/.markdownlint.yml b/.github/linters/.markdownlint.yml index 8ba6e877214..1eb082c8f40 100644 --- a/.github/linters/.markdownlint.yml +++ b/.github/linters/.markdownlint.yml @@ -19,20 +19,13 @@ # Rules by id # ############### MD001: false -MD009: false -MD012: false MD013: false -MD018: false -MD022: false MD024: false MD025: false MD026: false MD028: false MD029: false -MD031: false -MD032: false MD033: false -MD034: false MD036: false MD037: false MD040: false diff --git a/.markdownlintrc b/.markdownlintrc index 1ae42ae5d54..e6c16f0a5c3 100644 --- a/.markdownlintrc +++ b/.markdownlintrc @@ -1,23 +1,16 @@ { "MD001": false, - "MD009": false, - "MD012": false, "MD013": false, - "MD018": false, - "MD022": false, "MD024": false, "MD025": false, "MD026": false, "MD028": false, "MD029": false, - "MD031": false, - "MD032": false, "MD033": false, - "MD034": false, "MD036": false, "MD037": false, "MD040": false, "MD041": false, "MD045": false, "MD053": false -} \ No newline at end of file +} diff --git a/website/src/blog/2013-09-12-jquery-steps-form-wizard.md b/website/src/blog/2013-09-12-jquery-steps-form-wizard.md index 84f922ff520..d4176f93636 100644 --- a/website/src/blog/2013-09-12-jquery-steps-form-wizard.md +++ b/website/src/blog/2013-09-12-jquery-steps-form-wizard.md @@ -8,7 +8,7 @@ authorUrl: https://github.com/rstaib authorImageUrl: https://avatars0.githubusercontent.com/u/4325318?s=100&v=4 --- -This blog article was previously published on http://www.rafaelstaib.com/post/How-to-create-a-Form-Wizard-using-jQuery-Steps. +This blog article was previously published on . ## Motivation diff --git a/website/src/blog/2018-09-02-hot-chocolate-0.4.5.md b/website/src/blog/2018-09-02-hot-chocolate-0.4.5.md index a4b7b5a741c..c64041f27dd 100644 --- a/website/src/blog/2018-09-02-hot-chocolate-0.4.5.md +++ b/website/src/blog/2018-09-02-hot-chocolate-0.4.5.md @@ -81,4 +81,3 @@ With version 0.5 we will focus on subscriptions and custom directives. Custom will allow for writing field resolver middlewares that alter or replace the default execution behavior. Subscriptions is one of our last spec gaps. - diff --git a/website/src/blog/2019-03-19-logging-with-hotchocolate.md b/website/src/blog/2019-03-19-logging-with-hotchocolate.md index a13e4451b61..3004d267c34 100644 --- a/website/src/blog/2019-03-19-logging-with-hotchocolate.md +++ b/website/src/blog/2019-03-19-logging-with-hotchocolate.md @@ -212,4 +212,3 @@ Another example is our [Apollo Tracing implementation](https://github.com/Chilli I hope this little field trip into our instrumentation API gives a little outlook of an often-overlooked feature that is coming with version 9. All of what I showed in this blog is available with preview 5 (9.0.0-preview.5) that we released today. We will add stitching related events with the next view preview builds. - diff --git a/website/src/blog/2019-03-31-hot-chocolate-0.8.1.md b/website/src/blog/2019-03-31-hot-chocolate-0.8.1.md index bec5078e8c0..c0c12321214 100644 --- a/website/src/blog/2019-03-31-hot-chocolate-0.8.1.md +++ b/website/src/blog/2019-03-31-hot-chocolate-0.8.1.md @@ -60,4 +60,3 @@ For more information on what other bugs we fixed head over to our [changelog](ht ## Version 9 Development We have made a lot of headway with the new type system that is coming with version 9. Also, we are working on the `@defer` directive at the moment. We will give a more detailed update on the next major version in a separate blog post. Version 9 is really shaping up to become our biggest release so far. - diff --git a/website/src/blog/2019-04-11-integration-tests.md b/website/src/blog/2019-04-11-integration-tests.md index 19c1cf22a94..229cbbeeda3 100644 --- a/website/src/blog/2019-04-11-integration-tests.md +++ b/website/src/blog/2019-04-11-integration-tests.md @@ -174,7 +174,7 @@ result.MatchSnapshot(o => For more information about how snapshooter works head over to their repository: -https://github.com/SwissLife-OSS/snapshooter + ## Schema Tests diff --git a/website/src/blog/2020-03-18-entity-framework/2020-03-18-entity-framework.md b/website/src/blog/2020-03-18-entity-framework/2020-03-18-entity-framework.md index c1e0e02bf1b..c35cc857460 100644 --- a/website/src/blog/2020-03-18-entity-framework/2020-03-18-entity-framework.md +++ b/website/src/blog/2020-03-18-entity-framework/2020-03-18-entity-framework.md @@ -455,7 +455,7 @@ We have explored tooling with which we can explore the schema before issuing the If we would print our schema it would now look like the following. -> The schema SDL can be downloaded from http://localhost:5000/schema. +> The schema SDL can be downloaded from . ```graphql schema { diff --git a/website/src/blog/2021-01-20-hot-chocolate-logging/2021-01-10-hot-chocolate-logging.md b/website/src/blog/2021-01-20-hot-chocolate-logging/2021-01-10-hot-chocolate-logging.md index 128bb0a6ac7..c480f3afeef 100644 --- a/website/src/blog/2021-01-20-hot-chocolate-logging/2021-01-10-hot-chocolate-logging.md +++ b/website/src/blog/2021-01-20-hot-chocolate-logging/2021-01-10-hot-chocolate-logging.md @@ -273,7 +273,7 @@ You can drill down on each one if these queries, and see the actual query as wel Just like for the `ConsoleQueryLogger` class, we need to create a similar class for our MiniProfiler to work. I've done that in our example repository and named the class `MiniProfilerQueryLogger`. -https://github.com/pkellner/hot-chocolate-query-logging/blob/main/MiniProfilerQueryLogger.cs + It also implements `DiagosticEventListener` just like `ConsoleQueryLogger` did. It gets passed in the request context, but instead of logging to the console with the `ILogger` interface and the `ConsoleLoggerExtension`, it simply calls the MiniProfiler API directly. diff --git a/website/src/blog/2021-05-30-entity-framework/2020-03-18-entity-framework.md b/website/src/blog/2021-05-30-entity-framework/2020-03-18-entity-framework.md index 8f3b88f22e2..bc974db1a7c 100644 --- a/website/src/blog/2021-05-30-entity-framework/2020-03-18-entity-framework.md +++ b/website/src/blog/2021-05-30-entity-framework/2020-03-18-entity-framework.md @@ -455,7 +455,7 @@ We have explored tooling with which we can explore the schema before issuing the If we would print our schema it would now look like the following. -> The schema SDL can be downloaded from http://localhost:5000/schema. +> The schema SDL can be downloaded from . ```graphql schema { diff --git a/website/src/blog/2023-02-08-new-in-hot-chocolate-13/2023-02-08-new-in-hot-chocolate-13.md b/website/src/blog/2023-02-08-new-in-hot-chocolate-13/2023-02-08-new-in-hot-chocolate-13.md index f5838195f6d..e2cf6eae7de 100644 --- a/website/src/blog/2023-02-08-new-in-hot-chocolate-13/2023-02-08-new-in-hot-chocolate-13.md +++ b/website/src/blog/2023-02-08-new-in-hot-chocolate-13/2023-02-08-new-in-hot-chocolate-13.md @@ -614,14 +614,18 @@ dotnet install HotChocolate.Data.Marten With version 12, we introduced the Azure Functions integration but only targeted in-process Azure Functions. Now, with Hot Chocolate 13, we have doubled down on Azure Functions and provided the ability to now run in the isolated process model, along with templates for both. 1. Install the HotChocolate Templates. + ```bash dotnet new install HotChocolate.templates ``` + 2. Chose your template to install or take a spin with both. + ```bash dotnet new graphql-azf --output .\hc-graphql-azf dotnet new graphql-azf-ip --output .\hc-graphql-azf-ip ``` + Or use Visual Studio. ![HotChocolate Azure Functions Project Templates](az-func-templates-vs.png) diff --git a/website/src/docs/bananacakepop/v2/apis/client-registry.md b/website/src/docs/bananacakepop/v2/apis/client-registry.md index 4d3b3fcd5c7..a7ce7ca5fc8 100644 --- a/website/src/docs/bananacakepop/v2/apis/client-registry.md +++ b/website/src/docs/bananacakepop/v2/apis/client-registry.md @@ -3,11 +3,11 @@ title: "Client Registry" --- ![Image](images/client-registry-1.png) -The client registries is an important tool for managing your GraphQL Clients. It provides a centralized location for clients and queries. +The client registries is an important tool for managing your GraphQL Clients. It provides a centralized location for clients and queries. You can use the client registry to manage your clients and their queries. It allows you to validate your queries against the schema, ensuring that all the operations defined by a client are compatible with the current schema. This validation step is critical to prevent the execution of invalid queries that might result in runtime errors. -# Understanding Clients +# Understanding Clients A client, in the context of a GraphQL API, is an entity that interacts with the API by defining and executing GraphQL operations. These operations are stored on the API as persisted queries. @@ -36,11 +36,11 @@ The number of active client versions can vary depending on the nature of the cli On the other hand, for mobile clients, you often have multiple versions active simultaneously. This is because users may be using different versions of the app, and not all users update their apps at the same time. -Once a client version is no longer in use, it reaches its end of life. At this point, you can unpublish the client version from the client registry. This will remove its persisted queries from distribution, and they will no longer be validated against the schema. +Once a client version is no longer in use, it reaches its end of life. At this point, you can unpublish the client version from the client registry. This will remove its persisted queries from distribution, and they will no longer be validated against the schema. ## The Operations File -In the context of GraphQL, the operations file is a structured file that holds a collection of persisted queries for a client. This file serves as a reference for the client to manage and execute specific operations against a GraphQL API. +In the context of GraphQL, the operations file is a structured file that holds a collection of persisted queries for a client. This file serves as a reference for the client to manage and execute specific operations against a GraphQL API. ### Understanding the Format and Structure @@ -64,17 +64,17 @@ Several GraphQL clients have built-in support for this Relay-style operations fi # Setting Up a Client Registry -To set up a client registry, first, visit `eat.bananacakepop.com` and sign up for an account. Next, you'll need to download and install Barista, the .NET tool used to manage your client registry. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). +To set up a client registry, first, visit `eat.bananacakepop.com` and sign up for an account. Next, you'll need to download and install Barista, the .NET tool used to manage your client registry. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). After installing Barista, create a new API either through the Bananacakepop UI or the CLI. In the UI, simply right-click the document explorer and select "New API." If you prefer using the CLI, ensure you're logged in with the command `barista login`, then create a new API with the command `barista api create`. With these steps complete, you are ready to start using the client registry. -To get the id of your API, use the command `barista api list`. This command will list all of your APIs, their names, and their ids. You will need the id of your API to perform most operations on the schema registry. +To get the id of your API, use the command `barista api list`. This command will list all of your APIs, their names, and their ids. You will need the id of your API to perform most operations on the schema registry. # Using Persisted Queries To use persisted queries, the server needs to know how to translate the hash into the corresponding GraphQL operation. This is where the client registry comes in. The client registry maintains a mapping of hashes to query keys, informing the server which hash corresponds to which query. This allows the server to efficiently look up and execute the appropriate query when it receives a request from a client. -To connect your HotChocolate server to the client registry, you need the `BananaCakePop.Services` NuGet package. This package contains the `AddBananaCakePopServices()` extension method, which can be used to configure the client registry. +To connect your HotChocolate server to the client registry, you need the `BananaCakePop.Services` NuGet package. This package contains the `AddBananaCakePopServices()` extension method, which can be used to configure the client registry. To install the Banana Cake Pop services, run the following command in your project's root directory: @@ -103,9 +103,11 @@ public void ConfigureServices(IServiceCollection services) > **Tip: Using Environment Variables** > > Alternatively, you can set the required values using environment variables. This method allows you to call `AddBananaCakePopServices` without explicitly passing parameters. +> >- `BCP_API_KEY` maps to `ApiKey` >- `BCP_API_ID` maps to `ApiId` >- `BCP_STAGE` maps to `Stage` +> >```csharp >public void ConfigureServices(IServiceCollection services) >{ @@ -116,10 +118,12 @@ public void ConfigureServices(IServiceCollection services) > .UsePersistedQueryPipeline(); // Enable the persisted query pipeline >} >``` +> >In this setup, the API key, ID, and stage are set through environment variables. -## Block Ad-Hoc Queries -While you want to allow ad-hoc queries during development, you might want to disable them in production. +## Block Ad-Hoc Queries + +While you want to allow ad-hoc queries during development, you might want to disable them in production. This can be done by setting the `OnlyAllowPersistedQueries` option to `true` in the `ModifyRequestOptions` method. ```csharp @@ -134,7 +138,7 @@ public void ConfigureServices(IServiceCollection services) } ``` -You can also customize the error message that is returned when an ad-hoc query is sent to the server. +You can also customize the error message that is returned when an ad-hoc query is sent to the server. ```csharp public void ConfigureServices(IServiceCollection services) @@ -154,7 +158,6 @@ public void ConfigureServices(IServiceCollection services) } ``` - # Integrating with Continuous Integration Integrating the client registry into your Continuous Integration/Continuous Deployment (CI/CD) pipeline maximizes their benefits. It ensures that the clients in your API are always up-to-date and tested against potential breaking changes. @@ -167,7 +170,7 @@ As you release new versions of your clients, the client registry helps manage th The general flow for the client registry involves three main steps: validating the client, uploading it to the registry, and publishing it. -1. **Validate the Client**: The first step takes place during your Pull Request (PR) build. Here, you validate the client against the API using `barista client validate` command. This ensures that the client is compatible with the API and will not break existing functionality. +1. **Validate the Client**: The first step takes place during your Pull Request (PR) build. Here, you validate the client against the API using `barista client validate` command. This ensures that the client is compatible with the API and will not break existing functionality. 2. **Upload the Client**: The second step takes place during your release build. Here, you upload the client to the registry using the `barista client upload` command. This command requires the `--tag` and `--api-id` options. The `--tag` option specifies the tag for the client, and the `--api-id` option specifies the ID of the API to which you are uploading. This command create a new version of the client with the specified tag. The tag is a string that can be used to identify the client. It can be any string, but it is recommended to use a version number, such as `v1` or `v2`; or a commit hash, such as `a1b2c3d4e5f6g7h8i9j0k1l2m3n`. The tag is used to identify the client when publishing it. diff --git a/website/src/docs/bananacakepop/v2/apis/fusion.md b/website/src/docs/bananacakepop/v2/apis/fusion.md index 67b47594866..4e1357ed03e 100644 --- a/website/src/docs/bananacakepop/v2/apis/fusion.md +++ b/website/src/docs/bananacakepop/v2/apis/fusion.md @@ -3,36 +3,41 @@ title: "Fusion" --- ![Image](images/fusion-0.png) -BananaCakePop can be used as your orchestrator for your Fusion Gateway. It deeply integrates with your development workflow and allows you to publish, validate, consume and monitor your Fusion Gateway. - +BananaCakePop can be used as your orchestrator for your Fusion Gateway. It deeply integrates with your development workflow and allows you to publish, validate, consume and monitor your Fusion Gateway. ![Image](images/fusion-2.png) On the fusion dashboard you can now see the tracing information of your gateway and your subgraphs. # Dashboard + The fusion dashboard gives you a quick overview of your gateway and subgraphs. It shows you the status of your gateway and the status of your subgraphs. You can also see the latest telemetry data insights of your gateway and subgraphs. ## Topology + ![Image](images/fusion-3.png) The topology view shows you the connections between your gateway and your subgraphs. You can also see which clients are connected to your gateway and how many operations they are executing. ## Status + ![Image](images/fusion-4.png) The status view shows you a quick overview of the status of your gateway. With the indicators for latency, throughput and errors you see how your gateway statistics developed between the previous and the current time range. You also see the essential information about your gateway, such as the version, the stage, how many subgraphs are connected and how many clients are connected. ## Insights + ![Image](images/fusion-5.png) -The subgraph insights show you a quick overview over your connected subgraphs. You can see the latency, throughput and error rate of each subgraph. +The subgraph insights show you a quick overview over your connected subgraphs. You can see the latency, throughput and error rate of each subgraph. + +# Gateway Management -# Gateway Management With fusion you compose your gateway configuration locally when you deploy a subgraph. This means that you somehow need to inform your gateway that there is a new configuration available. With Banana Cake Pop you can automate this process. You can configure your gateway to automatically pull the latest configuration from Banana Cake Pop. This way you can be sure that your gateway always has the latest configuration. You can also validate your configuration against the schema and client registry to make sure that your change does not break any clients. ## Configure your gateway + To configure your fusion gateway to pull the configuration from Banana Cake Pop, you need to install the BananaCakePop.Services package. You can do this by running the following command in your project's root directory: ```bash @@ -55,19 +60,22 @@ builder.Services > **Tip: Using Environment Variables** > > Alternatively, you can set the required values using environment variables. This method allows you to call `ConfigureFromCloud` without explicitly passing parameters. +> >- `BCP_API_KEY` maps to `ApiKey` >- `BCP_API_ID` maps to `ApiId` >- `BCP_STAGE` maps to `Stage` +> >```csharp > builder.Services > .AddFusionGatewayServer() > .ConfigureFromCloud(); >``` +> >In this setup, the API key, ID, and stage are set through environment variables. Now your gateway will be notified whenever there is a new configuration available and will automatically pull it. -## Configure Your Subgraphs +## Configure Your Subgraphs To set up your subgraphs to be linked with your gateway, you need to follow these steps: @@ -108,7 +116,7 @@ services > **Tip: Using Environment Variables** > -> Alternatively, you can also set the required values using environment variables. +> Alternatively, you can also set the required values using environment variables. This configuration enables your subgraph to interact with the BananaCakePop services, including telemetry and instrumentation. @@ -130,28 +138,30 @@ Here’s an example of what the `subgraph-config.json` file should look like: } ``` -This file is required for the topology to recognize and display your subgraph correctly. +This file is required for the topology to recognize and display your subgraph correctly. ### Step 4: Pack your subgraph and compose your Gateway -After configuring your subgraph you have to `pack` your subgraph and `compose` your gateway. +After configuring your subgraph you have to `pack` your subgraph and `compose` your gateway. This process links your subgraph with the gateway, ensuring a cohesive GraphQL architecture. ## Integration into your CI/CD pipeline -The deployment of a subgraph is a multi step process. To integrate BananaCakePop into this process you need to install Barista, the BananaCakePop CLI. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). + +The deployment of a subgraph is a multi step process. To integrate BananaCakePop into this process you need to install Barista, the BananaCakePop CLI. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). + ```bash dotnet new tool-manifest dotnet tool install Barista ``` -You will also need the [Command Line Tools](https://www.nuget.org/packages/HotChocolate.Fusion.CommandLine) for packing and composing your subgraph. +You will also need the [Command Line Tools](https://www.nuget.org/packages/HotChocolate.Fusion.CommandLine) for packing and composing your subgraph. ```bash dotnet tool install HotChocolate.Fusion.CommandLine ``` - ### 1. Pack the subgraph + All changes to the gateway originate from a subgraph. Once the subgraph is ready to be deployed, you need to pack it. Packing a subgraph will create a subgraph package file that contains the schema, the extensions and the configuration of the subgraph. To easily access the newest schema and extensions, you can use the `schema export` command from the [Command Line Extension](/docs/hotchocolate/v13/server/command-line). This command exports your current schema into a specified output file. @@ -163,7 +173,8 @@ dotnet fusion subgraph pack This step is usually done in a separate build step in your CI/CD pipeline where you build and test your project before you go into the deployment phase. -### 2. Wait for a deployment slot +### 2. Wait for a deployment slot + Once your changes are ready to be deployed, you need to wait for a deployment slot. There can only ever be one deployment at the time. If there is already a deployment in progress, you need to wait until it is finished. Banana Cake Pop helps you coordinate your subgraph deployments. You register for a deployment by calling: @@ -179,6 +190,7 @@ dotnet barista fusion-configuration publish begin \ This command will complete once your turn has come and you can start deploying your subgraph. ### 3. Start the deployment + Once you have a deployment slot, you need to notify Banana Cake Pop that you are still interested in the slot. You do this by calling: ```bash @@ -186,15 +198,17 @@ dotnet barista fusion-configuration publish start --api-key <> ``` ### 4. Configure the subgraph + As most likely, your connection information is different from environment to environment, you need to configure the url of your subgraph. You can do this by calling: -```bash +```bash dotnet fusion subgraph config set http \ --url <> -c path/to/your/subgraph/config.fsp ``` ### 5. Compose the subgraph + To compose the subgraph, you first need to fetch the latest configuration from Banana Cake Pop. You can do this by calling: ```bash @@ -214,6 +228,7 @@ dotnet fusion compose -p ./gateway.fgp -s path/to/your/subgraph/config.fsp ``` ### 6. Validate the subgraph (optional) + If you want to make sure that your subgraph is compatible with the schema and client registry, you can validate it by calling: ```bash @@ -227,9 +242,11 @@ dotnet barista fusion-configuration publish cancel --api-key <> ``` ### 7. Deploy the subgraph + Now it's time to deploy your subgraph to your infrastructure ### 8. Commit the deployment + To complete the deployment, you need to commit the deployment. This will notify Banana Cake Pop that you are done with the deployment and that the next deployment can start. Banana Cake Pop will also notify your gateway that the deployment is finished and that it can pull the latest configuration. You can commit the deployment by calling: @@ -239,12 +256,13 @@ dotnet barista fusion-configuration publish commit --api-key <> ``` # Distributed Telemetry + ![Image](images/fusion-1.png) Banana Cake Pop provides a distributed telemetry solution for your Fusion Gateway. It allows you to monitor your gateway and all your subgraphs in one place. You can inspect the traces of your operations on the gateway and see how they are executed on the subgraphs. To enable telemetry for your gateway and subgraphs, all of them need to be configured to send telemetry data to Banana Cake Pop. Your subgraphs can be configured to send telemetry data by using the [BananaCakePop.Services](https://www.nuget.org/packages/BananaCakePop.Services/) package. You can find more information about how to configure your subgraphs in the [Open Telemetry](/docs/bananacakepop/v2/apis/open-telemetry) guide. -To send telemetry data from the gateway you need to add the instrumentation and the exporter to your gateway. +To send telemetry data from the gateway you need to add the instrumentation and the exporter to your gateway. ```csharp builder.Services @@ -262,6 +280,7 @@ builder.Services ``` Now your gateway will send the telemetry data to Banana Cake Pop. To connect your subgraphs to the gateway, you need to add an extension to your `subgraph-config.json`. You need to specify the `apiId` of the subgraph + ```json { "subgraph": "Order", diff --git a/website/src/docs/bananacakepop/v2/apis/open-telemetry.md b/website/src/docs/bananacakepop/v2/apis/open-telemetry.md index 6e6663ef76c..425342f70ee 100644 --- a/website/src/docs/bananacakepop/v2/apis/open-telemetry.md +++ b/website/src/docs/bananacakepop/v2/apis/open-telemetry.md @@ -3,7 +3,7 @@ title: "Open Telemetry" --- ![Image](images/telemetry-0.png) -Banana Cake Pop can collect your open telemetry data and visualize your traces in the app. +Banana Cake Pop can collect your open telemetry data and visualize your traces in the app. With telemetry you can get a better understanding of how your application is performing and where you can improve it. ![Image](images/telemetry-1.png) @@ -51,9 +51,11 @@ public void ConfigureServices(IServiceCollection services) > **Tip: Using Environment Variables** > > Alternatively, you can set the required values using environment variables. This method allows you to call `AddBananaCakePopServices` without explicitly passing parameters. +> >- `BCP_API_KEY` maps to `ApiKey` >- `BCP_API_ID` maps to `ApiId` >- `BCP_STAGE` maps to `Stage` +> >```csharp >public void ConfigureServices(IServiceCollection services) >{ @@ -72,26 +74,31 @@ public void ConfigureServices(IServiceCollection services) > }); >} >``` +> >In this setup, the API key, ID, and stage are set through environment variables. - # Monitoring Dashboard + The monitoring dashboard in Banana Cake Pop offers various metrics and visualizations to understand your service's performance better. ## Changing the time range + ![Image](images/telemetry-2.png) -You can change the time range of the dashboard by clicking on the time range selector in the top right corner of the dashboard. +You can change the time range of the dashboard by clicking on the time range selector in the top right corner of the dashboard. You can either customize the time range or select one of the predefined ranges. ## Latency + ![Image](images/telemetry-3.png) The latency graph shows the average latency of your service over time. You can also see the 95th and the 99th percentile of the latency. ## Throughput + ![Image](images/telemetry-4.png) The throughput graph shows you the operations per minute over time. You can see how many operations are executed on your service and how many of them failed. ## Clients + ![Image](images/telemetry-5.png) You can track how many requests are done by each client. This helps you to understand which client is impacting your system the most. To track this, your clients need to send two headers with each request: @@ -100,12 +107,14 @@ To track this, your clients need to send two headers with each request: - `GraphQL-Client-Version` - The version of the client ## Errors + ![Image](images/telemetry-6.png) Shows you the number of operations with errors over time. ## Insights + ![Image](images/telemetry-7.png) -This insights show you a list of executed operations. You can see the latency, the throughput and also how many percent of the operations had errors. You also have a column impact, which will help you to understand which operations are impacting your system the most. You can sort the columns by clicking on the column header. +This insights show you a list of executed operations. You can see the latency, the throughput and also how many percent of the operations had errors. You also have a column impact, which will help you to understand which operations are impacting your system the most. You can sort the columns by clicking on the column header. By clicking on an operation, you can see the telemetry information about the operation and it's traces. @@ -113,13 +122,16 @@ By clicking on an operation, you can see the telemetry information about the ope On the top right corner you can change from the operation insights to the resolver insights view. # Operation Dashboard + ![Image](images/telemetry-9.png) You can drill down into the telemetry information of a single operation by clicking on it in the insights view. ## Latency Error and Throughput + Theses graphs show you the latency, error rate and throughput of the selected operation over time similar to the graphs on the monitoring dashboard. ## Latency Distribution + ![Image](images/telemetry-10.png) This graph shows you the distribution of different traces of the selected operation. This way you can quickly see outliers and understand how the operation is performing. @@ -127,8 +139,9 @@ This graph shows you the distribution of different traces of the selected operat You can also select a time range in the graph. This selection will impact which traces are shown in the trace table. You can for example select the slow operations on the right and inspect why they are slow. ## Traces + ![Image](images/telemetry-12.png) -On the very bottom of the page you see sample traces of the selected operation with all of the spans. +On the very bottom of the page you see sample traces of the selected operation with all of the spans. If you click on a trace, the sidebar will show additional information about the trace including all the attributes of it. ![Image](images/telemetry-13.png) diff --git a/website/src/docs/bananacakepop/v2/apis/operation-reporting.md b/website/src/docs/bananacakepop/v2/apis/operation-reporting.md index 82e5cfc0892..55d25e66192 100644 --- a/website/src/docs/bananacakepop/v2/apis/operation-reporting.md +++ b/website/src/docs/bananacakepop/v2/apis/operation-reporting.md @@ -36,9 +36,11 @@ public void ConfigureServices(IServiceCollection services) > **Tip: Using Environment Variables** > > Alternatively, you can set the required values using environment variables. This method allows you to call `AddBananaCakePopServices` without explicitly passing parameters. +> >- `BCP_API_KEY` maps to `ApiKey` >- `BCP_API_ID` maps to `ApiId` >- `BCP_STAGE` maps to `Stage` +> >```csharp >public void ConfigureServices(IServiceCollection services) >{ @@ -48,6 +50,7 @@ public void ConfigureServices(IServiceCollection services) > .AddBananaCakePopServices() >} >``` +> >In this setup, the API key, ID, and stage are set through environment variables. # Viewing Reported Operations @@ -55,6 +58,7 @@ public void ConfigureServices(IServiceCollection services) Once Operation Reporting is enabled and configured, all GraphQL operations processed by your server will be reported to Banana Cake Pop. These operations can be viewed and analyzed in the `Operations` tab within the Banana Cake Pop interface. ![Image](images/operation-reporting-2.png) + 1. Click the `Operations` tab in Banana Cake Pop to view the list of reported operations. 2. The name of the executed operation. 3. Click on `V` to expand the operation and view the details. diff --git a/website/src/docs/bananacakepop/v2/apis/overview.md b/website/src/docs/bananacakepop/v2/apis/overview.md index 22e610f67fc..724a8d61660 100644 --- a/website/src/docs/bananacakepop/v2/apis/overview.md +++ b/website/src/docs/bananacakepop/v2/apis/overview.md @@ -3,30 +3,34 @@ title: Apis --- ![Image](images/apis-6.png) -An API within the context of Banana Cake Pop, refers to an representation of your GraphQL Servers. +An API within the context of Banana Cake Pop, refers to an representation of your GraphQL Servers. This representation is more than a mere conceptual framework — it serves as a practical tool that allows you to group your documents and share common settings like connection and authorization parameters among them. Additionally, an API forms the foundation for your client registry, schema registry setup and the telemetry. For more detailed information on these features, refer to the [Schema Registry](/docs/bananacakepop/v2/apis/schema-registry) guide the [Client Registry](/docs/bananacakepop/v2/apis/client-registry) and the [Telemetry](/docs/bananacakepop/v2/apis/open-telemetry) guide. - # API Types + ![Image](images/apis-2.png) ## API Collection + ![Image](images/apis-5.png) A compilation of GraphQL Documents with shared connection settings, enabling the grouping of documents for sharing with your t. ## API Service + ![Image](images/apis-3.png) Incorporates all features of an API Collection and adds the capability to register your schema and clients in the schema registry. It also includes the use of telemetry for service monitoring. This type is ideal for representing a single deployment service or a subgraph. ## API Gateway + ![Image](images/apis-4.png) Encompasses all the features of the API Service, along with the ability to publish and manage fusion configuration. Additionally, it supports distributed telemetry for comprehensive monitoring of your Gateway. # Creating an API + ![Image](images/apis-1.png) Creating an API in Banana Cake Pop is a user-friendly process. There are three methods available: diff --git a/website/src/docs/bananacakepop/v2/apis/schema-registry.md b/website/src/docs/bananacakepop/v2/apis/schema-registry.md index 698ac5000a5..3be0f090863 100644 --- a/website/src/docs/bananacakepop/v2/apis/schema-registry.md +++ b/website/src/docs/bananacakepop/v2/apis/schema-registry.md @@ -3,9 +3,9 @@ title: "Schema & Client Registry" --- ![Image](images/schema-registry-0.png) -The schema registries is an essential tool for managing your GraphQL APIs. It provides a centralized location for storing, managing, and distributing your GraphQL schema definitions. +The schema registries is an essential tool for managing your GraphQL APIs. It provides a centralized location for storing, managing, and distributing your GraphQL schema definitions. -With the schema registry, you can upload and store the schema of your API, making it accessible to your development team and other services. +With the schema registry, you can upload and store the schema of your API, making it accessible to your development team and other services. ![Image](images/schema-registry-1.png) The schema registry enables you to validate your schemas and clients against previous versions, ensuring that changes to your service do not break existing functionality, deeply integrated into your CI/CD pipeline. @@ -17,11 +17,11 @@ Together with the client registry, you can maintain the integrity of your API an # Understanding Schemas -In the context of GraphQL APIs, a schema is the blueprint that defines the shape of your data and specifies the capabilities of the API. It outlines the types of queries and mutations that can be executed against your API. +In the context of GraphQL APIs, a schema is the blueprint that defines the shape of your data and specifies the capabilities of the API. It outlines the types of queries and mutations that can be executed against your API. A schema is more than just a technical specification; it is a contract between your API and your clients. By understanding and managing schema changes, you can ensure that this contract remains valid and that your API and clients can evolve together without breaking. -Each stage of your API can have one active schema. This active schema is the one against which all requests are validated. +Each stage of your API can have one active schema. This active schema is the one against which all requests are validated. ## Schema Changes @@ -29,7 +29,8 @@ Changes to the schema can be categorized into three levels of severity based on 1. **Safe**: These changes don't affect the existing functionality. Examples include changes to descriptions or adding a new optional field to a type. Safe changes are generally backward compatible and don't require modifications to existing clients. -Examples are: +Examples are: + - Adding a new field to an object type - Adding a new optional argument to a field or directive - Adding a new type @@ -37,19 +38,21 @@ Examples are: 2. **Dangerous**: These changes could potentially break existing functionality, depending on how your consumers interact with your API. An example of a dangerous change is adding a new member to an enum. If the client is not prepared to handle the new member, it might result in unexpected behavior. Examples are: + - Adding a new member to an enum - Adding a new implementation to an interface 3. **Breaking**: These changes will break existing functionality if the affected parts of the schema are being used by clients. Examples include changing the type of a field, adding a required field to an input type, removing a field, or adding a new required argument to a field or directive. Examples are: + - Removing a field from an object type - Changing the type of a field - Change a non-null field to a nullable field Breaking changes need to be managed with care to avoid disruptions to the service. It's important to ensure that all clients can handle these changes before they are introduced. This can be accomplished by versioning your clients and managing the lifecycle of client versions, as described in the section [Understanding Clients](/docs/bananacakepop/v2/apis/client-registry#understanding-clients)]. -## Extracting the Schema +## Extracting the Schema Extracting your GraphQL API's schema can be beneficial for various purposes, such as documentation, testing, and version control. Here are some methods to extract the schema: @@ -88,13 +91,14 @@ public async Task Schema_Should_Not_Change() schema.MatchSnapshot(); } ``` + # Setting Up a Schema Registry -To set up a schema registry, first, visit `eat.bananacakepop.com` and sign up for an account. Next, you'll need to download and install Barista, the .NET tool used to manage your schema registry. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). +To set up a schema registry, first, visit `eat.bananacakepop.com` and sign up for an account. Next, you'll need to download and install Barista, the .NET tool used to manage your schema registry. You can find more information about Barista in the [Barista Documentation](/docs/barista/v1). After installing Barista, create a new API either through the Bananacakepop UI or the CLI. In the UI, simply right-click the document explorer and select "New API." If you prefer using the CLI, ensure you're logged in with the command `barista login`, then create a new API with the command `barista api create`. With these steps complete, you are ready to start using the schema registry. -To get the id of your API, use the command `barista api list`. This command will list all of your APIs, their names, and their ids. You will need the id of your API to perform most operations on the schema registry. +To get the id of your API, use the command `barista api list`. This command will list all of your APIs, their names, and their ids. You will need the id of your API to perform most operations on the schema registry. # Integrating with Continuous Integration @@ -102,7 +106,7 @@ Integrating the schema registry and into your Continuous Integration/Continuous To interact with the schema registry from the pipeline, you will need a API key. You can generate an api key directly with Barista using the command `barista api-key create`. Make sure to copy the key and store it in a secure location. The key will not be displayed again. -You can then use the key to authenticate with the schema registry using the `--api-key` option. +You can then use the key to authenticate with the schema registry using the `--api-key` option. The schema and client registries work hand-in-hand to ensure the smooth functioning of your API. As you make changes to your schema, the schema registry helps manage these changes, preventing inadvertent breaking changes and preserving a history of your schemas. As you validate, upload, and publish new schemas, the client registry ensures that your clients remain compatible with these changes. @@ -110,7 +114,7 @@ The schema and client registries work hand-in-hand to ensure the smooth function The general flow for the schema registry involves three main steps: validating the schema, uploading it to the registry, and publishing it. -1. **Validate the Schema **: The first step takes place during your Pull Request (PR) build. Here, you validate the schema against the API using the `barista schema validate` command. This ensures that the schema is compatible with the API and will not break existing functionality. +1. **Validate the Schema **: The first step takes place during your Pull Request (PR) build. Here, you validate the schema against the API using the `barista schema validate` command. This ensures that the schema is compatible with the API and will not break existing functionality. 2. **Upload the Schema**: The second step takes place during your release build. Here, you upload the schema to the registry using the `barista schema upload` command. This command requires the `--tag` and `--api-id` options. The `--tag` option specifies the tag for the schema, and the `--api-id` option specifies the ID of the API to which you are uploading. This command create a new version of the schema with the specified tag. The tag is a string that can be used to identify the schema. It can be any string, but it is recommended to use a version number, such as `v1` or `v2`; or a commit hash, such as `a1b2c3d4e5f6g7h8i9j0k1l2m3n`. The tag is used to identify the schema when publishing it. diff --git a/website/src/docs/bananacakepop/v2/apis/stages.md b/website/src/docs/bananacakepop/v2/apis/stages.md index 6f81ad606ed..b4e50dc8a5f 100644 --- a/website/src/docs/bananacakepop/v2/apis/stages.md +++ b/website/src/docs/bananacakepop/v2/apis/stages.md @@ -5,7 +5,7 @@ title: Stages # Working with Stages ![Screenshot of the Stages overview](images/stages-0.png) -A stage represents an environment of your service, such as development, staging, or production. Each stage can have an active schema and multiple active client versions. +A stage represents an environment of your service, such as development, staging, or production. Each stage can have an active schema and multiple active client versions. Stages are integral to the lifecycle management of your GraphQL APIs. They enable you to manage different environments of your service, such as development, staging, or production. Each stage can have an active schema, multiple active client versions and telemetry reports. The active schema and client versions for a stage represent the current state of your API for that environment. @@ -19,7 +19,7 @@ If you do not have stages yet, you can go the the `Stages` tab and click on `Use You can always edit these stages or add new ones by clicking the `Edit Stages` button. ![Screenshot of the Stages overview](images/stages-2.png) -The stages dialog allows you to add and edit stages. You can also delete stages, but only if they are not used by any client or schema. +The stages dialog allows you to add and edit stages. You can also delete stages, but only if they are not used by any client or schema. Stages are edited in a yaml editor. The default configuration looks like this: @@ -55,5 +55,3 @@ prod: This configuration defines two QA stages, `QA 1` and `QA 2`. Both of them come after the `Development` stage. The `Production` stage comes after both QA stages. It will result in the following stage order: ![Image](images/stages-3.png) - - diff --git a/website/src/docs/bananacakepop/v2/bcp-services.md b/website/src/docs/bananacakepop/v2/bcp-services.md index 1b122c47a88..f5f910d2837 100644 --- a/website/src/docs/bananacakepop/v2/bcp-services.md +++ b/website/src/docs/bananacakepop/v2/bcp-services.md @@ -5,16 +5,19 @@ title: Connect your API BananaCake Pop can be smoothly integrated into your HotChocolate server, enabling utilization of the Persisted Query Storage found within the client registry, to report operations and collect open telemetry. Your server will establish a connection with BananaCake Pop, retrieving persisted queries based on their unique hashes. Additional information on the client registry can be found [here](/docs/bananacakepop/v2/apis/client-registry). ## Getting Started + To get started, follow these steps: 1. Set up a client registry as instructed [here](/docs/bananacakepop/v2/apis/client-registry). 2. Install the BananaCakePop package from NuGet using the following command: + ```bash dotnet add package BananaCakePop.Services ``` 3. Configure your services as shown in the following code snippet: + ```csharp var builder = WebApplication.CreateBuilder(args); diff --git a/website/src/docs/bananacakepop/v2/documents/authentication.md b/website/src/docs/bananacakepop/v2/documents/authentication.md index 66b30a3d30f..f1a01a4e897 100644 --- a/website/src/docs/bananacakepop/v2/documents/authentication.md +++ b/website/src/docs/bananacakepop/v2/documents/authentication.md @@ -2,7 +2,7 @@ title: Authentication --- -Banana Cake pop offers support for various authentication flows. The following guide details how to use these authentication flows to retrieve a token from an identity server and send the Authorization header to the server. +Banana Cake pop offers support for various authentication flows. The following guide details how to use these authentication flows to retrieve a token from an identity server and send the Authorization header to the server. ![BCP Authentication Flow](images/auth-0.png) @@ -19,7 +19,7 @@ BCP supports three types of authentication flows: # Basic Authentication -Basic Authentication is a built-in authentication scheme of the HTTP protocol. It works by sending HTTP requests with an Authorization header. This header includes the word 'Basic' followed by a space and a base64-encoded string of the format 'username:password'. +Basic Authentication is a built-in authentication scheme of the HTTP protocol. It works by sending HTTP requests with an Authorization header. This header includes the word 'Basic' followed by a space and a base64-encoded string of the format 'username:password'. ![Basic Authentication Fields](images/auth-1.png) @@ -44,9 +44,10 @@ You will need to provide at least the token. The following fields are available: - **Authorization Header**: A preview of the header that will be used for authentication. This field is auto-generated based on the provided token and prefix. Learn more about Bearer Token Authentication [here](https://swagger.io/docs/specification/authentication/bearer-authentication/). -# OAuth 2.0 - -OAuth 2.0 authentication flow is a industry-standard authorization framework. It allows third-party applications to gain limited access to a web service through a server that supports the OAuth 2.0 protocol. Most major identity providers support OAuth 2.0, including Auth0, Okta, AWS Cognito, Azure AD, and more. + +# OAuth 2.0 + +OAuth 2.0 authentication flow is a industry-standard authorization framework. It allows third-party applications to gain limited access to a web service through a server that supports the OAuth 2.0 protocol. Most major identity providers support OAuth 2.0, including Auth0, Okta, AWS Cognito, Azure AD, and more. In .NET, OAuth 2.0 is implemented by [Duende IdentityServer](https://duendesoftware.com/products/identityserver) and [OpenIddict](https://documentation.openiddict.com/). @@ -65,9 +66,9 @@ The following fields are available required: - **[Grant Type](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3)**: This is the method an application uses to obtain an access token. Common values include 'authorization_code', 'client_credentials', 'password', and 'refresh_token'. Each type serves a different use case, such as a web application, machine-to-machine, mobile apps, etc. -- **Authorization URL**: This is the URL to which your application directs the user in the initial step of the authorization process. It usually looks something like 'https://auth.example.com/authorize'. +- **Authorization URL**: This is the URL to which your application directs the user in the initial step of the authorization process. It usually looks something like ''. -- **Access Token URL**: This is the URL your application uses to obtain the access token from the authorization server. It's typically of the form 'https://auth.example.com/token'. +- **Access Token URL**: This is the URL your application uses to obtain the access token from the authorization server. It's typically of the form ''. - **[Client ID](https://datatracker.ietf.org/doc/html/rfc6749#section-2.2)**: This is a public identifier for your application, issued by the authorization server when you register your application. It's used to identify your application to the user during authorization. @@ -83,13 +84,13 @@ The following fields are available required: - **[State](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1)**: This is an opaque value that is used to maintain state between the request and the callback, mitigating CSRF attacks. It's a good practice to use a unique value for each authorization request. -- **[Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3)**: Defines how client credentials are sent to the server. They can be sent as a Basic Auth Header or in the Request Body. +- **[Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3)**: Defines how client credentials are sent to the server. They can be sent as a Basic Auth Header or in the Request Body. - **Header Prefix**: This is the prefix that appears before the token in the Authorization header. The default is 'Bearer', as described in [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750), but it could also be 'Token' or other custom strings. - **Audience**: This is the intended audience of the token, typically the identifier of the resource server that should accept the token. -- **Resource**: The target resource that the application wants to access. +- **Resource**: The target resource that the application wants to access. - **Origin**: This is used in browser-based applications to indicate the origin of the request and mitigate CSRF attacks. @@ -107,8 +108,8 @@ Learn more about OAuth 2.0 [here](https://oauth.net/2/). In BCP, you can fetch the authentication token using two different methods: -1. **Fetch Button in Authentication Settings**: - +1. **Fetch Button in Authentication Settings**: + Located at the bottom of the authentication settings is a button labeled `Fetch`. Clicking this will retrieve the authentication token. Once the token is fetched, you also have options to `Clear` it or `Refresh` it (if a refresh token was requested). In the desktop application, there's an additional feature to `Reset the session on identity server`. This is particularly useful because your authentication session on your identity server is persisted in the browser, meaning you don't need to sign in repeatedly. If you wish to log in as a different user, you can reset your session by clicking this button. @@ -123,9 +124,8 @@ In BCP, you can fetch the authentication token using two different methods: These two methods allow you to conveniently manage and initiate your authentication flows, providing you with flexibility to cater to different use-case scenarios. -## Redirect URL +## Redirect URL -In the context of BCP (Banana Cake Pop), the Redirect URL plays a crucial role, particularly when you're using BCP within a web browser rather than the desktop application. +In the context of BCP (Banana Cake Pop), the Redirect URL plays a crucial role, particularly when you're using BCP within a web browser rather than the desktop application. The Redirect URL is where your browser is directed to after the authentication process. It must be configured to point back to the URL where BCP is hosted. This is essential because BCP needs to retrieve the authorization code from this URL to exchange it for a token. - diff --git a/website/src/docs/bananacakepop/v2/documents/connection-settings.md b/website/src/docs/bananacakepop/v2/documents/connection-settings.md index ce72a0b86bf..7e79f43ec2b 100644 --- a/website/src/docs/bananacakepop/v2/documents/connection-settings.md +++ b/website/src/docs/bananacakepop/v2/documents/connection-settings.md @@ -7,15 +7,19 @@ The Connection Settings in Banana Cake Pop allow you to configure various option ![Connection-Settings](./images/connection-settings-0.png) # Schema Endpoint + The Schema Endpoint refers to the URL of your GraphQL server. It is the endpoint used to send queries and mutations. Configure this setting with the appropriate URL to establish a connection with your GraphQL server. # Subscription Endpoint + The Subscription Endpoint represents the URL used to send subscriptions to the GraphQL server. By default, it is inferred from the Schema Endpoint. Specify the subscription URL if it differs from the Schema Endpoint. # SSE Subscription Endpoint + If you utilize SSE (Server-Sent Events) subscriptions, the SSE Subscription Endpoint should be provided. This URL specifies the endpoint for SSE subscriptions. By default, it is inferred from the Schema Endpoint. # Subscription Protocol + The Subscription Protocol setting allows you to choose the protocol for handling subscriptions. Banana Cake Pop supports the following options: - **Auto**: Banana Cake Pop negotiates the protocol with the server automatically based on server capabilities. @@ -24,9 +28,11 @@ The Subscription Protocol setting allows you to choose the protocol for handling - **Apollo Websocket**: Banana Cake Pop uses the deprecated [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) protocol from Apollo. # Use HTTP GET + By enabling the Use HTTP GET option, Banana Cake Pop will use HTTP GET instead of HTTP POST for executing queries and mutations. This can be useful in certain scenarios or for compatibility with specific GraphQL servers. # Include Cookies (cross-origin) + Enabling the Include Cookies (cross-origin) option ensures that cookies are included when sending queries and mutations to the GraphQL server. This is particularly relevant in cross-origin situations where cookies are required for authentication or session management. The Connection Settings provide you with the flexibility to customize the connection parameters and communication behavior with your GraphQL server. Configure these settings according to your server's requirements and the desired functionality of your application. diff --git a/website/src/docs/bananacakepop/v2/documents/index.md b/website/src/docs/bananacakepop/v2/documents/index.md index e9b7fc2be69..99ef14b5446 100644 --- a/website/src/docs/bananacakepop/v2/documents/index.md +++ b/website/src/docs/bananacakepop/v2/documents/index.md @@ -7,28 +7,37 @@ The Document View is a feature that allows users to work with documents and API ![Image](images/document-0.png) # 1. Operations + The Operations section is where you can write and execute your queries, mutations, and subscriptions. It provides a convenient interface for interacting with the GraphQL API. # 2. Schema Reference + The Schema Reference section allows you to explore the schema in a tree view or the explorer view. It provides detailed information about the available schema and its components. For more information on using the Schema Reference, refer to the [Schema Reference](/docs/bananacakepop/v2/documents/schema-reference) guide. # 3. Schema Definition + The Schema Definition section displays the schema definition in SDL (Schema Definition Language) format. It allows you to inspect the schema structure and understand its various types and fields. Refer to the [Schema Definition](/docs/bananacakepop/v2/documents/schema-definition) guide for further details. # 4. Document Status Indicator + The Document Status Indicator visually represents whether the current document is saved or not. A white dot indicates that the document is not saved, while a different icon may indicate a saved or modified state. # 5. Query Editor + The Query Editor provides a dedicated space for writing your queries, mutations, and subscriptions. It offers features such as syntax highlighting, auto-completion, and error checking to assist in query composition. Learn more about using the query editor in the [Operations](/docs/bananacakepop/v2/documents/operations) guide. # 6. Response Pane + The Response Pane displays the response of your queries, mutations, and subscriptions. It shows the data returned by the API and provides a structured view for easier analysis. Refer to the [Response Pane](/docs/bananacakepop/v2/documents/response) guide for additional information. # 7. Schema Indicator + The Schema Indicator is a visual cue that indicates the connection status with the GraphQL server and the successful retrieval of the schema. A green circle represents a connected state. # 8. Connected Schema Endpoint + This section displays the currently connected schema endpoint, providing information about the GraphQL server being accessed. # 9. Settings + The Document Settings section allows you to configure various settings specific to the document. Refer to the [Connection Settings](/docs/bananacakepop/v2/documents/connection-settings) guide for detailed information about it. You can also configure the authentication settings for the document. Refer to the [Authentication Settings](/docs/bananacakepop/v2/documents/authentication) guide for more details. diff --git a/website/src/docs/bananacakepop/v2/documents/operations.md b/website/src/docs/bananacakepop/v2/documents/operations.md index 3724514281c..ee2c8c4d50f 100644 --- a/website/src/docs/bananacakepop/v2/documents/operations.md +++ b/website/src/docs/bananacakepop/v2/documents/operations.md @@ -7,22 +7,29 @@ The Operations Pane provides a comprehensive interface for writing GraphQL queri ![Banana Cake Pop - Operations Pane](./images/operations-0.png) # **1. Operations Editor** + The Operations Editor is a text editor within the Operations Pane where you can write your GraphQL queries, mutations, and subscriptions. It provides syntax highlighting, intellisense, and validation to assist you in writing accurate queries. # **2. Inline Run Button** + The Inline Run Button allows you to execute your query directly from the Operations Editor. By clicking this button, your query will be sent to the GraphQL server, and the response will be displayed in the Response Pane. # **3. Format Button** + The Format Button helps you maintain proper query formatting according to common formatting rules. When clicked, it automatically formats your query and updates the content in the Operations Editor. # **4. Run Button** + The Run Button enables you to execute your query with a single click. Similar to the Inline Run Button, clicking this button will send your query to the GraphQL server, and the response will be shown in the Response Pane. # **5. Variables Panel** + The Variables Panel allows you to define variables for your query. You can specify the variable name, type, and default value. These variables can then be utilized within your query, making it more dynamic and reusable. # **6. Headers Panel** + The Headers Panel enables you to define headers for your query. You can specify the header name and value, which will be included when sending the query to the GraphQL server. This feature is useful for including authentication tokens or other custom headers required by your API. For authentication, you can also use the Authentication Settings feature, which is described in the [Authentication Settings](/docs/bananacakepop/v2/documents/authentication) section. # **7. File Upload Panel** + The File Upload Panel provides functionality for uploading files to the GraphQL server. You can specify the file name and contents within this panel. This feature works in conjunction with the `Upload` scalar type, a special type in GraphQL that facilitates file uploads. It follows the multipart form request specification to send files to the GraphQL server. For more details, refer to the [documentation](/docs/hotchocolate/v13/server/files) on file uploads in GraphQL. diff --git a/website/src/docs/bananacakepop/v2/documents/response.md b/website/src/docs/bananacakepop/v2/documents/response.md index 1db6675382b..0a9d1688af2 100644 --- a/website/src/docs/bananacakepop/v2/documents/response.md +++ b/website/src/docs/bananacakepop/v2/documents/response.md @@ -12,15 +12,18 @@ The pane is divided into two sections: 3. Additionally, you can get a brief overview of the response status code, the duration, and the size of the last executed request on the top right of the pane. # Response Section + ![Banana Cake Pop - Response Pane](./images/response-1.png) This part of the pane displays the JSON response of the executed query. In case you have deferred results, this view amalgamates all results into one JSON object. For those using subscriptions, this view will display the most recent result of the subscription. # Transport Request Body + ![Banana Cake Pop - Response Pane](./images/response-2.png) Found under a separate tab, this section provides the raw JSON request sent to the server. # Transport Details + ![Banana Cake Pop - Response Pane](./images/response-3.png) This pane provides in-depth details of the request and response. Here is a rundown of the information displayed: @@ -30,16 +33,19 @@ This pane provides in-depth details of the request and response. Here is a rund * **Response Headers:** Provide information about the HTTP response, such as the content-length, content-security-policy, and strict-transport-security. # Transport Error + ![Banana Cake Pop - Response Pane](./images/response-4.png) This tab displays a JSON representation of any errors returned by the server when the request fails. # Logs + ![Banana Cake Pop - Response Pane](./images/response-5.png) The Logs tab records all logs generated during the execution of a query. This includes all requests, patch responses, subscription results, errors, and warnings. Clicking on a log entry will prompt the editor below to show more details about the log entry. # History + ![Banana Cake Pop - Response Pane](./images/response-6.png) The History tab keeps track of all the queries that have been executed in the current document. Clicking on a history entry will load the corresponding query into the editor, allowing you to review the response. diff --git a/website/src/docs/bananacakepop/v2/documents/schema-reference.md b/website/src/docs/bananacakepop/v2/documents/schema-reference.md index 2baef261c25..5c3e4f8cb5b 100644 --- a/website/src/docs/bananacakepop/v2/documents/schema-reference.md +++ b/website/src/docs/bananacakepop/v2/documents/schema-reference.md @@ -5,21 +5,27 @@ title: "Schema Reference" The Schema Reference feature allows you to inspect and explore the schema of your GraphQL server. It provides valuable information about the available types, fields, and directives within the schema. This section describes the components and functionalities of the Schema Reference. # Explorer View + ![Explorer View](./images/reference-0.png) ## 1. View Switcher + The View Switcher allows you to toggle between two different views: the Tree View and the Explorer View. Each view provides a unique way to navigate and explore the schema. You are currently viewing the Explorer View. ## 2. Selected Type Details + This section displays detailed information about the currently selected type, including its fields and arguments. It offers insights into the structure and properties of the selected type. ## 3. Summary Information + The Summary Information provides quick statistics about the number of types and directives present in the schema. It offers a high-level overview of the schema's composition. ## 4. Search Bar + The Search Bar allows you to search for specific types and fields within the schema. You can enter keywords or names to quickly locate relevant components. # Tree View + ![Tree View](./images/reference-1.png) In the Tree View, you start with the root types of the schema, such as Query, Mutation, and Subscription. Clicking on a root type expands it to reveal the available fields associated with that type. By clicking on any field, you can further explore the schema and its nested components. The right side of the interface provides detailed information about the selected field. diff --git a/website/src/docs/bananacakepop/v2/environments.md b/website/src/docs/bananacakepop/v2/environments.md index 4bf2aeede69..156a6e4ef72 100644 --- a/website/src/docs/bananacakepop/v2/environments.md +++ b/website/src/docs/bananacakepop/v2/environments.md @@ -4,30 +4,34 @@ title: Environments Environment variable provide a mechanism for reusing specific values across multiple documents. These variables are defined as key-value pairs. -Frequently used data, like URLs, tokens, and credentials, are commonly centrally managed as environment variable. -By doing so, these values can be referenced in your documents and changed in a single location for all you documents. You can also quickly switch between different values for different environments. +Frequently used data, like URLs, tokens, and credentials, are commonly centrally managed as environment variable. +By doing so, these values can be referenced in your documents and changed in a single location for all you documents. You can also quickly switch between different values for different environments. -For instance, you might store your API key as an environment variable, allowing it to be used universally in all your documents. +For instance, you might store your API key as an environment variable, allowing it to be used universally in all your documents. If the API key changes, you can just update the environment variable without having to manually alter each document. You can define multiple environments for a single workspace corresponding to various contexts or project stages (e.g., development, testing, production). The environments can be switched in the status bar. -When you have different project stages such as such as development (`https://serivce1.dev.company.com`), testing (`https://serivce1.test.company.com`), and production (`https://serivce1.prod.company.com`), you can for example set up the dynamic part of the url as a variable URL and incorporate it in all your urls (`https://serivce1.{{subdomain}}.company.com`). -By switching the active environment in Banana Cake Pop, the base URL will update automatically, streamlining your workflow. +When you have different project stages such as such as development (`https://serivce1.dev.company.com`), testing (`https://serivce1.test.company.com`), and production (`https://serivce1.prod.company.com`), you can for example set up the dynamic part of the url as a variable URL and incorporate it in all your urls (`https://serivce1.{{subdomain}}.company.com`). +By switching the active environment in Banana Cake Pop, the base URL will update automatically, streamlining your workflow. Similarly, identifiers such as client ID and client secret can be defined as environment variable, which make it convenient to work with. # Creating Environments + ![Screenshot showing the environment](images/env-0.png) To create a new environment, follow these steps: -1. Click on the environment icon on the left side of your screen. + +1. Click on the environment icon on the left side of your screen. 2. Click the Plus icon to create a new environment. 3. Enter a name for the environment. # Rename Environments + ![Screenshot showing the environment](images/env-1.png) -You can rename by right-clicking on the environment and selecting the 'Rename' option. +You can rename by right-clicking on the environment and selecting the 'Rename' option. # Specifying Variables + ![Screenshot showing the environment](images/env-2.png) To open the environment variable editor, click on the environment you would like to edit. @@ -36,15 +40,16 @@ To open the environment variable editor, click on the environment you would like 2. **Name**: The name of the environment variable. This name will be used to reference the variable in your documents. e.g. `{{ClientId}}`, `{{ClientSecret}}` `{{Subdomain}}` 3. **Value**: The value of the environment variable. This value will be substituted in your documents when the environment variable is referenced. 4. **Secret**: If an environment variable is marked as secret, it will be shown as a password field within the Banana Cake Pop interface. This feature is designed to help prevent accidental exposure of the value. Please note that marking a value as secret does not mean it is encrypted; it is simply visually obscured in the user interface. -5. **Apply**: Clicking the 'Apply' button will save the environment variables. - +5. **Apply**: Clicking the 'Apply' button will save the environment variables. # Switching Environments + ![Screenshot showing the environment](images/env-3.png) To switch environments, click on the environment name in the status bar. A dropdown menu will appear, listing all available environments. After selecting an environment, the environment variables of the selected environment will be active and applied to all documents. -# Using Variables +# Using Variables + ![Screenshot showing the environment](images/env-4.png) Once you have defined an environment variable, you can reference it in your documents by using the following syntax: `{{variable_name}}`. Environment variable can be employed in a variety of places within Banana Cake Pop, such as URLs, GraphQL Variables, and Connection Settings. When a request is executed, any referenced environment variable will be substituted with their respective values. diff --git a/website/src/docs/bananacakepop/v2/explore-the-ui/explorer.md b/website/src/docs/bananacakepop/v2/explore-the-ui/explorer.md index 416b60ccee3..999de2902c2 100644 --- a/website/src/docs/bananacakepop/v2/explore-the-ui/explorer.md +++ b/website/src/docs/bananacakepop/v2/explore-the-ui/explorer.md @@ -8,12 +8,12 @@ The Explorer is a versatile component utilized in various parts of the applicati ### 1. Quick Actions -The Explorer offers a set of quick actions that allow users to perform common tasks swiftly. In the provided example, the quick actions enable the creation of a document, folder, or API with just a few clicks. +The Explorer offers a set of quick actions that allow users to perform common tasks swiftly. In the provided example, the quick actions enable the creation of a document, folder, or API with just a few clicks. ### 2. Folder Node -Folder nodes within the Explorer can be expanded or collapsed by clicking on the arrow associated with them. The icon accompanying each folder node indicates its item type, aiding in quick identification and differentiation. +Folder nodes within the Explorer can be expanded or collapsed by clicking on the arrow associated with them. The icon accompanying each folder node indicates its item type, aiding in quick identification and differentiation. ### 3. Context Menu -Right-clicking on an item within the Explorer opens the context menu, which presents a list of actions that can be performed on the selected item. The context menu provides a convenient way to access item-specific operations and functions relevant to the current workspace context. +Right-clicking on an item within the Explorer opens the context menu, which presents a list of actions that can be performed on the selected item. The context menu provides a convenient way to access item-specific operations and functions relevant to the current workspace context. diff --git a/website/src/docs/bananacakepop/v2/getting-started.md b/website/src/docs/bananacakepop/v2/getting-started.md index 62ac3c161ae..922e1dfede4 100644 --- a/website/src/docs/bananacakepop/v2/getting-started.md +++ b/website/src/docs/bananacakepop/v2/getting-started.md @@ -1,10 +1,11 @@ --- title: "Getting Started" --- -Ready to explore the delicious features of Banana Cake Pop? In this getting started guide, we'll show you how to get up and running with Banana Cake Pop. +Ready to explore the delicious features of Banana Cake Pop? In this getting started guide, we'll show you how to get up and running with Banana Cake Pop. You have the option to choose between the convenience of the web app or the enhanced capabilities of the desktop version. We'll guide you through the setup process, so you can start enjoying all that Banana Cake Pop has to offer. Get ready to unlock the full potential of GraphQL with Banana Cake Pop. Choose your preferred option and follow the setup instructions to start enjoying the delicious features that Banana Cake Pop has to offer. + # Web App To begin your exploration, simply visit [eat.bananacakepop.com](https://eat.bananacakepop.com/) and experience the convenience of Banana Cake Pop's web-based version. This excellent starting point allows you to conveniently probe public GraphQL APIs and access most of the features that Banana Cake Pop offers. For an even more immersive experience, you can also install the web app as a Progressive Web App (PWA) on your device, providing a native-like experience. @@ -13,7 +14,7 @@ To begin your exploration, simply visit [eat.bananacakepop.com](https://eat.bana You can install the Banana Cake Pop App directly from our [download page](/products/bananacakepop). The download page provides DMG installers for macOS, x64 installers for Windows, and AppImage/Snap installers for Ubuntu and Ubuntu-based Linux distributions. Note that other Linux distributions or installer formats are currently unsupported. -## Package Managers +## Package Managers 1. **Homebrew**: If you have [Homebrew](https://brew.sh) installed, use this command to install the app: @@ -22,10 +23,13 @@ brew install --cask banana-cake-pop ``` 2. **Windows Package Manager**: For Windows 11 or a supported version of Windows 10 with the [Windows Package Manager](https://docs.microsoft.com/en-us/windows/package-manager/) installed, use: + ```powershell winget install banana-cake-pop ``` + 3. **Scoop**: To install on Windows 7, 10, or 11 using [Scoop](https://scoop.sh/), run these commands: + ```powershell scoop bucket add extras scoop install banana-cake-pop @@ -37,17 +41,16 @@ Upon successful installation, follow the steps in the [Your first Query](#your-f Lets guide you through the process of creating your first GraphQL query document using Banana Cake Pop. -**Step 1:** Start the Banana Cake Pop application. You should see an interface similar to this: +**Step 1:** Start the Banana Cake Pop application. You should see an interface similar to this: ![Banana Cake Pop - Start](./images/getting-started-0.png) **Step 2:** Click on the "Create Document" button to initiate the creation of your first query document. -**Step 3:** You'll see a new document called 'untitled 1' generated. Simultaneously, the connection settings dialog box will pop up automatically. -Now, input the following link into the 'Schema Endpoint' field: https://workshop.chillicream.com/graphql +**Step 3:** You'll see a new document called 'untitled 1' generated. Simultaneously, the connection settings dialog box will pop up automatically. +Now, input the following link into the 'Schema Endpoint' field: It should resemble this: ![Banana Cake Pop - Start](./images/getting-started-1.png) - **Step 4:** Click on the 'Apply' button. This will save your settings and close the dialog box. **Step 5:** At this point, your screen should look like this: @@ -59,7 +62,6 @@ Take note of the following key elements: 1. **Response Pane:** Here, you will see the output or response of your queries. 1. **Variables Pane:** This is where you can define variables for your query. - **Step 6:** The green circle at the top right next to the schema url indicates that you are connected to the GraphQL server and that your schema is fetched. You now have full intellisense for your queries. Copy the following GraphQL query and paste it into the 'Operations' editor area: ```graphql @@ -77,8 +79,8 @@ Take note of the following key elements: **Step 7:** Click on the 'Run' button. You should see a response with data in the 'Response' area. Congratulations, you have completed a GraphQL query! -**Step 8:** -Now, let's save your document. +**Step 8:** +Now, let's save your document. ![Banana Cake Pop - Start](./images/getting-started-3.png) Sign in to your account by clicking the 'Sign In' button on the user icon in the bottom left corner of the screen. If you don't have an account, you can create a new one. diff --git a/website/src/docs/bananacakepop/v2/index.md b/website/src/docs/bananacakepop/v2/index.md index 3054e60cc7a..2954f7cc22c 100644 --- a/website/src/docs/bananacakepop/v2/index.md +++ b/website/src/docs/bananacakepop/v2/index.md @@ -14,7 +14,7 @@ Are you hungry yet? [Let's get started!](/docs/bananacakepop/v2/getting-started) Whether you're building or consuming GraphQL APIs, Banana Cake Pop simplifies the process by allowing you to effortlessly build and execute GraphQL queries and mutations. Its intuitive UI enables you to visualize and explore your GraphQL schemas, making it easier to understand and work with complex structures. The powerful editor provides syntax highlighting, auto-completion, and error highlighting, helping you write GraphQL queries and mutations with ease. 2. **Collaboration** -Additionally, Banana Cake Pop places a strong emphasis on collaboration. It offers seamless team collaboration features, allowing developers to share documents, API configurations, environment settings and lets you collaborate on projects, and synchronize your work across multiple team members. By facilitating effective communication, Banana Cake Pop ensures that everyone on your team is on the same page, leading to more efficient and coordinated development efforts. +Additionally, Banana Cake Pop places a strong emphasis on collaboration. It offers seamless team collaboration features, allowing developers to share documents, API configurations, environment settings and lets you collaborate on projects, and synchronize your work across multiple team members. By facilitating effective communication, Banana Cake Pop ensures that everyone on your team is on the same page, leading to more efficient and coordinated development efforts. 3. **DevOps** Banana Cake Pop support you during the entire lifecycle of an API. With its schema and client registry, Banana Cake Pop ensures that your APIs are well-maintained and evolve seamlessly over time. Integrated into your development workflow, Banana Cake Pop helps you manage your APIs effectively, making easy to build and maintain high-quality APIs. @@ -27,6 +27,3 @@ The client registry feature of Banana Cake Pop complements the schema registry b 6. **Intuitive Interface** Banana Cake Pop provides a user-friendly interface that is easy to navigate, even for those new to GraphQL. Its clean and intuitive design makes it a pleasure to work with, enabling developers to focus on their tasks without unnecessary distractions or complications. - - - diff --git a/website/src/docs/bananacakepop/v2/integrations/express.md b/website/src/docs/bananacakepop/v2/integrations/express.md index 7d2362aca9c..168547e2406 100644 --- a/website/src/docs/bananacakepop/v2/integrations/express.md +++ b/website/src/docs/bananacakepop/v2/integrations/express.md @@ -75,6 +75,7 @@ bcpMiddleware({ mode: "self" }) // for `self` hosted version # Extended configuration ## Pin a specific version + To pin a specific version instead of using "latest": ```javascript @@ -85,6 +86,7 @@ bcpMiddleware({ ``` ## Use your own infrastructure + To use your own infrastructure: ```javascript @@ -95,6 +97,7 @@ bcpMiddleware({ ``` ## Custom options + To pass options supported by Banana Cake Pop GraphQL IDE: ```javascript @@ -119,9 +122,11 @@ bcpMiddleware({ | subscriptionProtocol | Specifies the protocol used for GraphQL subscriptions. | `SubscriptionProtocol` (optional) | # Recipes + Below are examples of how to use Banana Cake Pop Express Middleware with different GraphQL server setups. ## graphql-http + ```javascript import express from "express"; import { createHandler } from "graphql-http"; @@ -144,6 +149,7 @@ app.listen(3000, () => { ``` ## graphql-yoga + ```javascript import express from "express"; import { createYoga, createSchema } from "graphql-yoga"; @@ -164,6 +170,7 @@ app.listen(3000, () => { ``` ## express-graphql + ```javascript import express from "express"; import { graphqlHTTP } from "express-graphql"; @@ -189,6 +196,7 @@ app.listen(3000, () => { ``` ## Apollo Server + ```javascript import { ApolloServer } from "@apollo/server"; //... rest of the imports diff --git a/website/src/docs/bananacakepop/v2/integrations/hot-chocolate.md b/website/src/docs/bananacakepop/v2/integrations/hot-chocolate.md index eaaf748098b..bc5a3dd1e9e 100644 --- a/website/src/docs/bananacakepop/v2/integrations/hot-chocolate.md +++ b/website/src/docs/bananacakepop/v2/integrations/hot-chocolate.md @@ -25,7 +25,7 @@ app.UseEndpoints(endpoints => In this configuration, the GraphQL service remains at the `/graphql` endpoint, and Banana Cake Pop is served at the `/my-graphql-ui` endpoint. -# Disable the Middleware +# Disable the Middleware In some scenarios, you may not want to serve Banana Cake Pop, e.g., in a production environment. You can disable Banana Cake Pop by setting the `Enable` property to `false`: @@ -44,7 +44,7 @@ endpoints # Serve Modes -The `ServeMode` property controls which version of Banana Cake Pop to serve. The default mode is `Latest`, serving the most recent version of Banana Cake Pop from a CDN. +The `ServeMode` property controls which version of Banana Cake Pop to serve. The default mode is `Latest`, serving the most recent version of Banana Cake Pop from a CDN. You can also serve the embedded version (`Embedded`) of Banana Cake Pop, which is included in the package. - `Latest`: Serves the latest version of Banana Cake Pop from a CDN. diff --git a/website/src/docs/bananacakepop/v2/organizations/index.md b/website/src/docs/bananacakepop/v2/organizations/index.md index 1ca1da90209..19f4e2b8cc2 100644 --- a/website/src/docs/bananacakepop/v2/organizations/index.md +++ b/website/src/docs/bananacakepop/v2/organizations/index.md @@ -4,9 +4,10 @@ title: "Organizations" This guide will walk you through the features and functionalities of BCP Organizations, a structure designed to help teams and individuals work efficiently and effectively on GraphQL related services. # What is an Organization - An organization typically represents an entire entity or a larger unit within an entity. Each organization can host multiple workspaces, allowing further categorization and organization of resources. A workspace might correspond to a specific project, a specific team within the organization, or a group of related APIs. -Each BCP user has a personal organization. This is a private space for individual work or for projects that are not associated with any team or company organization. The personal organization is not visible to other users, is created by default and cannot be deleted. + An organization typically represents an entire entity or a larger unit within an entity. Each organization can host multiple workspaces, allowing further categorization and organization of resources. A workspace might correspond to a specific project, a specific team within the organization, or a group of related APIs. + +Each BCP user has a personal organization. This is a private space for individual work or for projects that are not associated with any team or company organization. The personal organization is not visible to other users, is created by default and cannot be deleted. # Creating an Organization @@ -18,13 +19,14 @@ You will be redirected to the management portal. Here you can create a new organ ![Picture showing the create button in the management portal](images/create-1.png) -Each organization has a unique name and a display name which can be set during creation. +Each organization has a unique name and a display name which can be set during creation. The name must be lowercase and may only include dashes (-) and underscores (_). ![Screenshot of the create organization screen](images/create-2.png) # Managing Organizations -To manage your organizations, you have to open the management portal. + +To manage your organizations, you have to open the management portal. ![Screenshot showing the manage button in the organization switcher](images/manage-0.png) @@ -32,9 +34,9 @@ In the client app, you can do this by clicking Manage Organizations' and then ' You can also navigate to [here](https://identity.chillicream.com/Organizations) to open the management portal and press 'Manage' on the organization that you like to manage. - # Switching Organizations -In Banana Cake Pop, you can be signed into multiple organizations at the same time and switch between them in the status bar. The organization switcher also allows you to create new organizations. + +In Banana Cake Pop, you can be signed into multiple organizations at the same time and switch between them in the status bar. The organization switcher also allows you to create new organizations. ![Screenshot showing the organization switcher in the status bar](images/switch-0.png) @@ -46,11 +48,12 @@ In Banana Cake Pop, you can be signed into multiple organizations at the same ti 2. This list show all the members of the organization and their role. -3. Members can be invited to join an organization via email. In the management overview section, the 'Invite User' button allows you to send an invitation email containing a join link. +3. Members can be invited to join an organization via email. In the management overview section, the 'Invite User' button allows you to send an invitation email containing a join link. 4. Open invitations are displayed below. You can revoke an invitation by clicking on the 'Cancel' button. Once an invitation is expired, you can resend it by clicking on the 'Resend' button. ## Joining an Organization + Invited users can join an organization in two ways: 1. By clicking on the join link they received via email. @@ -80,7 +83,7 @@ There are three distinct roles within an organization: Owner, Admin, and Collabo ![Screenshot showing the invite user button and the process](images/members-1.png) -You can manage the permissions of each member in the member list. +You can manage the permissions of each member in the member list. 1. Press the 'Edit' button on the right side of the member list to open the edit dialog. @@ -90,19 +93,19 @@ You can manage the permissions of each member in the member list. 4. You can also remove a member from the organization by clicking on the 'Revoke Access' button. -# Transferring Ownership +# Transferring Ownership -Ownership of the organization can be transferred to any existing member from the management portal. +Ownership of the organization can be transferred to any existing member from the management portal. In the danger zone section, click on the 'Transfer Ownership' button to open the transfer dialog. ![Screenshot showing the transfer ownership button and the process](images/danger-zone-0.png) -# Redirect URLs +# Redirect URLs -Each time a user signs into an organization from a new origin, a redirect URL must be added to the organization. +Each time a user signs into an organization from a new origin, a redirect URL must be added to the organization. This security measure is designed to prevent your access tokens from being leaked to any arbitrary site hosted by third parties. -If the user is a collaborator, they won't have the permissions to add the URL and will see an informative message. An admin, on the other hand, can directly add the URL to the organization. +If the user is a collaborator, they won't have the permissions to add the URL and will see an informative message. An admin, on the other hand, can directly add the URL to the organization. You can add the redirect URL in two ways: @@ -110,11 +113,11 @@ You can add the redirect URL in two ways: ![Screenshot showing the redirect URL prompt](images/redirect-0.png) -2. By adding the URL directly from the management portal. +2. By adding the URL directly from the management portal. ![Screenshot showing the redirect URL prompt](images/redirect-1.png) -In the portal you have more options to configure the allowed destinations. You can for example allow all localhost origins. Or disable the access to the web UI in the [cloud](https://eat.bananacakepop.com) +In the portal you have more options to configure the allowed destinations. You can for example allow all localhost origins. Or disable the access to the web UI in the [cloud](https://eat.bananacakepop.com) 1. Configure the allowed types of origins. 2. Add redirect Urls to the organization. diff --git a/website/src/docs/bananacakepop/v2/settings/index.md b/website/src/docs/bananacakepop/v2/settings/index.md index 5f870e5adce..ff569b2c82d 100644 --- a/website/src/docs/bananacakepop/v2/settings/index.md +++ b/website/src/docs/bananacakepop/v2/settings/index.md @@ -9,4 +9,3 @@ The Settings section provides users with various customization options. To acces Currently, the most significant setting available is the [Themes](/docs/bananacakepop/v2/settings/themes) feature. This allows users to personalize the appearance and visual style of the application. Please note that organization settings are exclusively accessible through the management portal. For more information about organization settings, refer to the [Organizations](/docs/bananacakepop/v2/organizations) documentation. - diff --git a/website/src/docs/bananacakepop/v2/settings/key-bindings.md b/website/src/docs/bananacakepop/v2/settings/key-bindings.md index dc916957340..2ce69df8452 100644 --- a/website/src/docs/bananacakepop/v2/settings/key-bindings.md +++ b/website/src/docs/bananacakepop/v2/settings/key-bindings.md @@ -54,5 +54,3 @@ A full list of all available keyboard shortcuts can be found clicking on the 'Ke - Reload Schema: CTRL + ALT + R - Show Operation: CTRL + SHIFT + O - Show Schema: CTRL + SHIFT + S - - diff --git a/website/src/docs/bananacakepop/v2/settings/themes.md b/website/src/docs/bananacakepop/v2/settings/themes.md index 3ffdf469ca0..478419780ed 100644 --- a/website/src/docs/bananacakepop/v2/settings/themes.md +++ b/website/src/docs/bananacakepop/v2/settings/themes.md @@ -21,4 +21,3 @@ Here are the available themes: **GitHub High Contrast Dark** ![GitHub High Contrast Dark](./images/theme-5.png) **GitHub High Contrast Light** ![GitHub High Contrast Light](./images/theme-6.png) - diff --git a/website/src/docs/bananacakepop/v2/subscriptions.md b/website/src/docs/bananacakepop/v2/subscriptions.md index 41db9d3763c..8f228eb954c 100644 --- a/website/src/docs/bananacakepop/v2/subscriptions.md +++ b/website/src/docs/bananacakepop/v2/subscriptions.md @@ -6,7 +6,7 @@ You can manage your subscriptions directly from the web portal, accessible throu # Creating a Subscription -When you do not have a subscription yet, you can create on in the 'Subscriptions' section of the management portal. Open the organization in the context of an owner or admin to see this section. +When you do not have a subscription yet, you can create on in the 'Subscriptions' section of the management portal. Open the organization in the context of an owner or admin to see this section. ![Screenshot showing the subscription](./images/subscription-2.png) Enter the number of seats you want to purchase and click on the 'Create' button. You will be redirected to the billing portal to complete the payment process. @@ -16,12 +16,11 @@ You have the option to pay monthly or annually. Annual payments are discounted. You can cancel your subscription at any time. The subscription will remain active until the end of the current billing period. You can also change your subscription plan at any time. Check out the [Changing a Subscription](#changing-a-subscription) section for more information. - # Changing a Subscription To change your subscription plan, follow these steps: -1. **Access the Management Portal:** Open the management portal by clicking ['Manage Organizations' -> 'Manage'](/docs/bananacakepop/v2/organizations#managing-organizations) option in the context menu of the bcp or by navigating to [here](https://identity.chillicream.com/Organizations). +1. **Access the Management Portal:** Open the management portal by clicking ['Manage Organizations' -> 'Manage'](/docs/bananacakepop/v2/organizations#managing-organizations) option in the context menu of the bcp or by navigating to [here](https://identity.chillicream.com/Organizations). 2. **Navigate to Subscriptions:** Within the management portal, click on 'Manage' in the subscription section. ![Screenshot showing the subscription](images/subscription-3.png) @@ -31,13 +30,14 @@ To change your subscription plan, follow these steps: # Expiry and Seats -Banana Cake Pops subscription model allows a certain number of users (seats) to join an organization based on your chosen subscription plan. +Banana Cake Pops subscription model allows a certain number of users (seats) to join an organization based on your chosen subscription plan. If your subscription expires, all users except the organization owner will be deactivated a few days after the expiration. The deactivated users will regain access once the subscription is renewed. If your organization reaches its maximum seat limit, no new users will be able to join the organization. You can manage this by either upgrading your subscription to allow for more seats or by removing existing users from the organization to free up seats. -# Billing +# Billing + In the client app you can directly access the billing portal by clicking 'Billing' and managing your running subscriptions: ![Description of visualization: Screenshot showing the subscription](images/subscription-1.png) diff --git a/website/src/docs/bananacakepop/v2/workspaces.md b/website/src/docs/bananacakepop/v2/workspaces.md index 17126f73cfe..0d14cdeed3d 100644 --- a/website/src/docs/bananacakepop/v2/workspaces.md +++ b/website/src/docs/bananacakepop/v2/workspaces.md @@ -4,13 +4,13 @@ title: Workspaces Workspaces are logical groups within an organization. A workspace could represent a team, a department, or a group of APIs that are related to each other. -Each workspace has its own APIs, documents, API documents, environments, and more. You cannot share resources between workspaces. +Each workspace has its own APIs, documents, API documents, environments, and more. You cannot share resources between workspaces. All members of an organization have default access to all workspaces and can edit the documents within them. In the future we will add more granular permissions to workspaces. -In Banana Cake Pop, you can switch between workspaces using the status bar. +In Banana Cake Pop, you can switch between workspaces using the status bar. ![Screenshot showing the workspace and organization switcher in the status bar](images/workspace-0.png) -At the moment, workspaces can only be created with barista. To create a new workspace, use the `barista workspace create` command. +At the moment, workspaces can only be created with barista. To create a new workspace, use the `barista workspace create` command. You can find out more about barista [here](/docs/barista/v1). diff --git a/website/src/docs/barista/v1/authentication.md b/website/src/docs/barista/v1/authentication.md index dd44a8ab595..03aee34d518 100644 --- a/website/src/docs/barista/v1/authentication.md +++ b/website/src/docs/barista/v1/authentication.md @@ -6,21 +6,21 @@ Barista offers two methods for authenticating your account: interactive login an # Interactive Login -To initiate the interactive login process, use the `barista login` command. This command opens a browser window where you can sign in using your preferred login provider. +To initiate the interactive login process, use the `barista login` command. This command opens a browser window where you can sign in using your preferred login provider. ```shell barista login ``` -Once logged in, you will be asked to select your default workspace. If you don't have a default workspace yet, go to [eat.bananacakepop.com](https://eat.bananacakepop.com) and sign in there. Upon signing in, a workspace will automatically be created for you. +Once logged in, you will be asked to select your default workspace. If you don't have a default workspace yet, go to [eat.bananacakepop.com](https://eat.bananacakepop.com) and sign in there. Upon signing in, a workspace will automatically be created for you. -> You can quickly navigate to the Banana Cake Pop site using the `barista launch` command. +> You can quickly navigate to the Banana Cake Pop site using the `barista launch` command. After you have selected your workspace, your setup is complete and you're ready to start using Barista. # API Key Authentication -The second method for authentication is via API keys. API keys are unique identifiers that grant access to your workspace without the need for interactive login. They are useful for automating tasks or for use in a Continuous Integration/Continuous Deployment (CI/CD) pipeline. +The second method for authentication is via API keys. API keys are unique identifiers that grant access to your workspace without the need for interactive login. They are useful for automating tasks or for use in a Continuous Integration/Continuous Deployment (CI/CD) pipeline. -You can use the `api-key` subcommand in Barista to manage your API keys. How you can manage the api keys, you can read in the [API Key Management](/docs/barista/v1/commands/api-key) section. +You can use the `api-key` subcommand in Barista to manage your API keys. How you can manage the api keys, you can read in the [API Key Management](/docs/barista/v1/commands/api-key) section. Remember to keep your API keys secure, as they provide full access to your workspace. If an API key is compromised, make sure to delete it and create a new one. diff --git a/website/src/docs/barista/v1/commands/api-key.md b/website/src/docs/barista/v1/commands/api-key.md index 757324ea307..4ef799f32bb 100644 --- a/website/src/docs/barista/v1/commands/api-key.md +++ b/website/src/docs/barista/v1/commands/api-key.md @@ -4,7 +4,7 @@ title: API Key Management The `barista api-key` command provides a set of subcommands that allow you to manage API keys. -# Create a Key +# Create a Key The `barista api-key create` command is used to create a new API key. @@ -18,7 +18,7 @@ barista api-key create --api-id abc123 - `--api-id `: Specifies the ID of the API for which you want to create a new API key. This ID can be retrieved with the `barista api list` command. You can set it from the environment variable `BARISTA_API_ID`. -# Delete a Key +# Delete a Key The `barista api-key delete` command is used to delete an API key by its ID. @@ -30,7 +30,7 @@ barista api-key delete api-key123 - ``: Specifies the ID of the API key you want to delete. -# List all Keys +# List all Keys The `barista api-key list` command is used to list all API keys of a workspace. diff --git a/website/src/docs/barista/v1/commands/api.md b/website/src/docs/barista/v1/commands/api.md index 4620728232b..2d4f5de7ca0 100644 --- a/website/src/docs/barista/v1/commands/api.md +++ b/website/src/docs/barista/v1/commands/api.md @@ -4,7 +4,7 @@ title: API Management The `barista api` command provides a set of subcommands that allow you to manage APIs. -# Create an API +# Create an API The `barista api create` command is used to create a new API. @@ -12,8 +12,7 @@ The `barista api create` command is used to create a new API. barista api create ``` - -# Delete an API +# Delete an API The `barista api delete` command is used to delete an API by its ID. @@ -33,7 +32,6 @@ The `barista api list` command is used to list all APIs of a workspace. barista api list ``` - # Show API Details The `barista api show` command is used to show the details of an API. @@ -46,7 +44,7 @@ barista api show abc123 - ``: Specifies the ID of the API whose details you want to see. -# Set API Settings +# Set API Settings The `barista api set-settings` command is used to set the settings of an API. diff --git a/website/src/docs/barista/v1/commands/client.md b/website/src/docs/barista/v1/commands/client.md index 31c9f3a4d78..171c3072e02 100644 --- a/website/src/docs/barista/v1/commands/client.md +++ b/website/src/docs/barista/v1/commands/client.md @@ -4,7 +4,7 @@ title: Client Management The `barista client` command provides a set of subcommands that allow you to upload, validate, publish, and unpublish client versions, as well as create a new client, list all clients of an API, and show details of a specific client. -# Publish a Client +# Publish a Client The `barista client publish` command is used to publish a client version to a stage. @@ -25,7 +25,7 @@ barista client publish \ - `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `barista api-key create` returns. You can set it from the environment variable `BARISTA_API_KEY`. -# Unpublish a Client +# Unpublish a Client The `barista client unpublish` command is used to unpublish a client version from a stage. @@ -40,7 +40,7 @@ barista client unpublish \ The options for the `unpublish` command are the same as for the `publish` command. -# Validate a Client +# Validate a Client The `barista client validate` command is used to validate a client version. @@ -79,7 +79,7 @@ barista client upload --tag v1.0.1 --operations-file ./operations.json --client- - `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `barista api-key create` returns. You can set it from the environment variable `BARISTA_API_KEY`. -# Create Client +# Create Client The `barista client create` command is used to create a new client. diff --git a/website/src/docs/barista/v1/commands/environment.md b/website/src/docs/barista/v1/commands/environment.md index 8c9e8abdada..d5cfe5710c8 100644 --- a/website/src/docs/barista/v1/commands/environment.md +++ b/website/src/docs/barista/v1/commands/environment.md @@ -4,7 +4,7 @@ title: Environment The `barista environment` command provides a set of subcommands that allow you to manage environments. -# Create a Environment +# Create a Environment The `barista environment create` command is used to create a new environment. @@ -12,8 +12,7 @@ The `barista environment create` command is used to create a new environment. barista environment create ``` - -# List all Environments +# List all Environments The `barista environment list` command is used to list all environments of a workspace. @@ -21,7 +20,6 @@ The `barista environment list` command is used to list all environments of a wor barista environment list ``` - # Show Environment Details The `barista environment show` command is used to show the details of an environment. @@ -33,4 +31,3 @@ barista environment show abc123 **Arguments:** - ``: Specifies the ID of the environment whose details you want to see. - diff --git a/website/src/docs/barista/v1/commands/logout.md b/website/src/docs/barista/v1/commands/logout.md index d61eabdf684..91d46a9acb5 100644 --- a/website/src/docs/barista/v1/commands/logout.md +++ b/website/src/docs/barista/v1/commands/logout.md @@ -2,7 +2,7 @@ **Description** -The `barista logout` command is used to log out of your user account on Barista. +The `barista logout` command is used to log out of your user account on Barista. To use the `barista logout` command, type it into your terminal as shown below: diff --git a/website/src/docs/barista/v1/commands/schema.md b/website/src/docs/barista/v1/commands/schema.md index e042c4c0ec4..88b9c655384 100644 --- a/website/src/docs/barista/v1/commands/schema.md +++ b/website/src/docs/barista/v1/commands/schema.md @@ -4,7 +4,7 @@ title: Schema Management The `barista schema` command provides a set of subcommands that allow you to upload, validate, and publish schemas. -# Publish a Schema +# Publish a Schema The `barista schema publish` command is used to publish a schema version to a stage. @@ -27,7 +27,7 @@ barista schema publish \ - `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `barista api-key create` returns. You can set it from the environment variable `BARISTA_API_KEY`. -# Validate a Schema +# Validate a Schema The `barista schema validate` command is used to validate a new client version. @@ -48,7 +48,7 @@ barista schema validate \ - `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `barista api-key create` returns. You can set it from the environment variable `BARISTA_API_KEY`. -# Upload a Schema +# Upload a Schema The `barista schema upload` command is used to upload a new schema version. diff --git a/website/src/docs/barista/v1/commands/stage.md b/website/src/docs/barista/v1/commands/stage.md index c03d1f3b512..03851e3bfd4 100644 --- a/website/src/docs/barista/v1/commands/stage.md +++ b/website/src/docs/barista/v1/commands/stage.md @@ -4,7 +4,7 @@ title: Stage Management The `barista stage` command provides a set of subcommands that allow you to manage stages. -# Edit Stages of an API +# Edit Stages of an API The `barista stage edit` command provides an interactive user interface for managing the stages of an API. The screen you see allows you to add new stages, save changes, edit existing stages, and delete stages. diff --git a/website/src/docs/barista/v1/commands/workspace.md b/website/src/docs/barista/v1/commands/workspace.md index 6e0a4a67ce9..b1238477fc6 100644 --- a/website/src/docs/barista/v1/commands/workspace.md +++ b/website/src/docs/barista/v1/commands/workspace.md @@ -4,7 +4,7 @@ title: Workspace Management The `barista workspace` command provides a set of subcommands that allow you to manage workspaces. -# Create a Workspace +# Create a Workspace The `barista workspace create` command is used to create a new workspace. @@ -12,8 +12,7 @@ The `barista workspace create` command is used to create a new workspace. barista workspace create ``` - -# Set Default Workspace +# Set Default Workspace The `barista workspace set-default` command is used to select a workspace and set it as your default workspace. @@ -21,8 +20,7 @@ The `barista workspace set-default` command is used to select a workspace and se barista workspace set-default ``` - -# List all Workspaces +# List all Workspaces The `barista workspace list` command is used to list all workspaces. @@ -30,7 +28,6 @@ The `barista workspace list` command is used to list all workspaces. barista workspace list ``` - # Show Workspace Details The `barista workspace show` command is used to show the details of a workspace. @@ -43,8 +40,7 @@ barista workspace show abc123 - ``: Specifies the ID of the workspace whose details you want to see. - -# Show Current Workspace +# Show Current Workspace The `barista workspace current` command is used to show the name of the currently selected workspace. diff --git a/website/src/docs/hotchocolate/v10/schema/custom-scalar-types.md b/website/src/docs/hotchocolate/v10/schema/custom-scalar-types.md index d84ce7e2996..96225667c60 100644 --- a/website/src/docs/hotchocolate/v10/schema/custom-scalar-types.md +++ b/website/src/docs/hotchocolate/v10/schema/custom-scalar-types.md @@ -73,7 +73,7 @@ This will ensure that the type inference works predictable and will by default i As I said before in most cases we do not need to do anything since Hot Chocolate has default bindings. -# Any Type +# Any Type The `Any` scalar is a special type that can be compared to `object` in c#. Any allows us to specify any literal or return any output type. diff --git a/website/src/docs/hotchocolate/v10/tutorials/index.md b/website/src/docs/hotchocolate/v10/tutorials/index.md index d567c637e73..b6b205aeca6 100644 --- a/website/src/docs/hotchocolate/v10/tutorials/index.md +++ b/website/src/docs/hotchocolate/v10/tutorials/index.md @@ -3,4 +3,4 @@ title: Tutorial --- We have created a tutorial that uses Entity Framework which you can follow here: -https://github.com/ChilliCream/graphql-workshop + diff --git a/website/src/docs/hotchocolate/v11/api-reference/migrate-from-10-to-11.md b/website/src/docs/hotchocolate/v11/api-reference/migrate-from-10-to-11.md index c2ca8876d65..0c60d2f3fa1 100644 --- a/website/src/docs/hotchocolate/v11/api-reference/migrate-from-10-to-11.md +++ b/website/src/docs/hotchocolate/v11/api-reference/migrate-from-10-to-11.md @@ -142,7 +142,7 @@ The serial execution for Entity Framework compatibility is gone. If you use Enti Another variant here is to use our scoped service feature that scopes services for the resolver pipeline. This is explained in our GraphQL Workshop project. -https://github.com/ChilliCream/graphql-workshop + # Schema / Resolvers diff --git a/website/src/docs/hotchocolate/v12/api-reference/apollo-federation.md b/website/src/docs/hotchocolate/v12/api-reference/apollo-federation.md index f306587fc23..c146d102821 100644 --- a/website/src/docs/hotchocolate/v12/api-reference/apollo-federation.md +++ b/website/src/docs/hotchocolate/v12/api-reference/apollo-federation.md @@ -711,6 +711,7 @@ query { ``` ## C# Records + Records can be decorated almost in the same way as classes to add Apollo Federation support. The above Product example as a positional record would look like this: diff --git a/website/src/docs/hotchocolate/v12/api-reference/extending-filtering.md b/website/src/docs/hotchocolate/v12/api-reference/extending-filtering.md index 223d35b76cd..514b9eeaf34 100644 --- a/website/src/docs/hotchocolate/v12/api-reference/extending-filtering.md +++ b/website/src/docs/hotchocolate/v12/api-reference/extending-filtering.md @@ -147,7 +147,7 @@ conventionDescriptor.Provider(); ## Custom Conventions Most of the time the descriptor API should satisfy your needs. -It is recommended to build extensions based on the descriptor API rather than creating a custom convention. +It is recommended to build extensions based on the descriptor API rather than creating a custom convention. However, if you want to have full control over naming and type creation, you can also override the methods you need on the `FilterConvention`. diff --git a/website/src/docs/hotchocolate/v12/api-reference/migrate-from-10-to-11.md b/website/src/docs/hotchocolate/v12/api-reference/migrate-from-10-to-11.md index 82a8258b77e..761746afac8 100644 --- a/website/src/docs/hotchocolate/v12/api-reference/migrate-from-10-to-11.md +++ b/website/src/docs/hotchocolate/v12/api-reference/migrate-from-10-to-11.md @@ -142,7 +142,7 @@ The serial execution for Entity Framework compatibility is gone. If you use Enti Another variant here is to use our scoped service feature that scopes services for the resolver pipeline. This is explained in our GraphQL Workshop project. -https://github.com/ChilliCream/graphql-workshop + # Schema / Resolvers diff --git a/website/src/docs/hotchocolate/v12/api-reference/visitors.md b/website/src/docs/hotchocolate/v12/api-reference/visitors.md index f8f635ea8ac..5df5d9b8bfb 100644 --- a/website/src/docs/hotchocolate/v12/api-reference/visitors.md +++ b/website/src/docs/hotchocolate/v12/api-reference/visitors.md @@ -67,7 +67,7 @@ autonumber Root->>Root: OnAfterLeave `query GetFoos` ``` -1. We start walking down the tree and _enter_.
+1. We start walking down the tree and _enter_.
2. Call `OnBeforeEnter(OperationDefinitionNode node, TContext context)` 3. Call `Enter(OperationDefinitionNode node, TContext context)` 4. Call `OnAfterEnter(OperationDefinitionNode node, TContext context)` diff --git a/website/src/docs/hotchocolate/v13/defining-a-schema/dynamic-schemas.md b/website/src/docs/hotchocolate/v13/defining-a-schema/dynamic-schemas.md index 25ecd7ce848..3a9468f439e 100644 --- a/website/src/docs/hotchocolate/v13/defining-a-schema/dynamic-schemas.md +++ b/website/src/docs/hotchocolate/v13/defining-a-schema/dynamic-schemas.md @@ -4,13 +4,13 @@ title: Dynamic Schemas In the world of SaaS, one size rarely fits all. With the ever-changing requirements and the need for high flexibility, schemas in a web application often need to be dynamic. In the context of GraphQL, a dynamic schema allows you to adapt the data structure exposed by your API according to varying conditions, be it different tenant, changing data sources, or configuration. -For instance, consider a Content Management System (CMS) where each tenant might require custom fields that are specific to their use case. Having a static GraphQL schema in such a scenario would mean that you need to anticipate all possible custom fields beforehand, which is not practical. A dynamic schema, on the other hand, allows you to add, remove, or modify the types and fields in your schema at runtime based on the specific needs of each tenant. Each tenant can have a different schema, and you can adapt the schema to the tenant's needs without having to redeploy your application. +For instance, consider a Content Management System (CMS) where each tenant might require custom fields that are specific to their use case. Having a static GraphQL schema in such a scenario would mean that you need to anticipate all possible custom fields beforehand, which is not practical. A dynamic schema, on the other hand, allows you to add, remove, or modify the types and fields in your schema at runtime based on the specific needs of each tenant. Each tenant can have a different schema, and you can adapt the schema to the tenant's needs without having to redeploy your application. While creating dynamic schemas in GraphQL offers substantial flexibility, it also comes with its own set of complexities. This is where the `ITypeModule` interface in Hot Chocolate comes into play. # What is `ITypeModule`? -`ITypeModule` is an interface introduced in Hot Chocolate that allows you to build a component that dynamically provides types to the schema building process. +`ITypeModule` is an interface introduced in Hot Chocolate that allows you to build a component that dynamically provides types to the schema building process. The `ITypeModule` interface consists of an event `TypesChanged` and a method `CreateTypesAsync`. Here is a brief overview of each: @@ -79,10 +79,10 @@ In this implementation, `CreateTypesAsync` reads a JSON file, parses it, and cre # Unsafe Type Creation -When working with dynamic schemas and the `ITypeModule` interface, one of the practices you'll encounter is the use of the `CreateUnsafe` method to create types. +When working with dynamic schemas and the `ITypeModule` interface, one of the practices you'll encounter is the use of the `CreateUnsafe` method to create types. The unsafe way to create types, as the name implies, bypasses some of the standard validation logic. This method is useful for advanced scenarios where you need more flexibility, such as when dynamically creating types based on runtime data. -The `CreateUnsafe` method allows you to create types directly from a `TypeDefinition`. +The `CreateUnsafe` method allows you to create types directly from a `TypeDefinition`. ```csharp ```csharp @@ -92,16 +92,16 @@ var typeDefinition = new ObjectTypeDefinition("DynamicType"); var dynamicType = ObjectType.CreateUnsafe(typeDefinition); ``` -Using `CreateUnsafe` method for type creation can be a complex task as it involves operating directly on the type definition. +Using `CreateUnsafe` method for type creation can be a complex task as it involves operating directly on the type definition. This allows for a lot of flexibility, but it also requires a deeper understanding of the Hot Chocolate type system. -Here are some examples of how you might use the `CreateUnsafe` method to create various types. +Here are some examples of how you might use the `CreateUnsafe` method to create various types. > This is by no means an exhaustive list, but it should give you an idea of how to use this feature. ## Creating an Object Type -Let's say we want to create a new object type representing a `Product` in an e-commerce system. +Let's say we want to create a new object type representing a `Product` in an e-commerce system. We would start by defining the `ObjectTypeDefinition`: ```csharp @@ -186,19 +186,21 @@ Now our `Product` object type has fields `id`, `name`, `price`, and `discountPri A resolver in Hot Chocolate is a delegate that fetches the data for a specific field. There are two types of resolvers: _async Resolvers_ and _pure Resolvers_. -1. **Async Resolvers**: +1. **Async Resolvers**: ```csharp public delegate ValueTask FieldResolverDelegate(IResolverContext context); ``` + _Async Resolvers_ are are typically async and have access to a `IResolverContext`. They are usually used for fetching data from services or databases. -2. **Pure Resolvers**: +2. **Pure Resolvers**: ```csharp public delegate object? PureFieldDelegate(IPureResolverContext context); ``` - _Pure Resolvers_ is used where no side-effects or async calls are needed. All your properties are turned into pure resolvers by Hot Chocolate. + + _Pure Resolvers_ is used where no side-effects or async calls are needed. All your properties are turned into pure resolvers by Hot Chocolate. The execution engine optimizes the execution of these resolvers (through inlining of the value completion) to make it significantly faster. The decision to use _async Resolvers_ or _pure Resolvers_ depends on your use case. If you need to perform asynchronous operations,or fetch data from services, you would use _async Resolvers_. If your resolver is simply retrieving data without any side effects, _pure Resolvers_ would be a more performant choice. @@ -246,7 +248,7 @@ type Product { Creating an Input Object Type is very similar to creating an Object Type. The major difference lies in the fact that Input Object Types are used in GraphQL mutations or as arguments in queries, whereas Object Types are used in GraphQL queries to define the shape of the returned data. Meaning you don't need to define resolvers for Input Object Types. -An Input Object Type can be created by defining an `InputObjectTypeDefinition` and using the `InputObjectType.CreateUnsafe` method. +An Input Object Type can be created by defining an `InputObjectTypeDefinition` and using the `InputObjectType.CreateUnsafe` method. Let's create an input object type representing a `ProductInput` which can be used to create or update a product: diff --git a/website/src/docs/hotchocolate/v13/defining-a-schema/input-object-types.md b/website/src/docs/hotchocolate/v13/defining-a-schema/input-object-types.md index 740e90ec956..914c32c31d2 100644 --- a/website/src/docs/hotchocolate/v13/defining-a-schema/input-object-types.md +++ b/website/src/docs/hotchocolate/v13/defining-a-schema/input-object-types.md @@ -195,11 +195,11 @@ public record BookingInput(string Title, string Author); # Default Values -In GraphQL, default values can be assigned to arguments and input types. These values are automatically utilized if no other value is provided when a query or mutation is executed. +In GraphQL, default values can be assigned to arguments and input types. These values are automatically utilized if no other value is provided when a query or mutation is executed. Default values are specified in the GraphQL schema by appending `= value` to the argument or input type definition. For example: `field(value: Int = 10)` would give `value` a default of 10. -Default values can be set for any input types, including scalars, enums, and input object types. They can also be used with list types and non-null types. +Default values can be set for any input types, including scalars, enums, and input object types. They can also be used with list types and non-null types. Consider the following schema: @@ -219,6 +219,7 @@ In the `user` query field, the `active` argument has a default value of `true`. In resolvers, arguments with default values are treated as optional. If the client does not provide a value, the resolver will receive the default value. This makes handling optional fields in your resolvers much easier. This means you can write the following query against the schema described before: + ```graphql query fetchUser { user { # active is not needed @@ -240,10 +241,10 @@ type Query { Despite the addition of the `role` argument, the `fetchUser` query can still be executed without supplying this new argument, as the `role` will default to `"user"`. ## Specifying DefaultValues -The `DefaultValueAttribute` or the `DefaultValue` method on the field descriptor, allow you to assign default values to your fields or arguments. -Consider the following scenario where we have a `UserInput` type with different fields like `name`, `active`. By default, we would like `active` to be `true`. +The `DefaultValueAttribute` or the `DefaultValue` method on the field descriptor, allow you to assign default values to your fields or arguments. +Consider the following scenario where we have a `UserInput` type with different fields like `name`, `active`. By default, we would like `active` to be `true`. @@ -305,16 +306,17 @@ input UserInput { active: Boolean! = true } ``` + ## Using GraphQL Syntax -It is also possible to specify default values using GraphQL value syntax. +It is also possible to specify default values using GraphQL value syntax. This comes in handy when you want to set default values that are more than just simple scalars. Like for example objects or lists. -Consider a scenario where we have a `UserProfileInput` type with a field `preferences`. The `preferences` field itself is an object containing various user preference settings. +Consider a scenario where we have a `UserProfileInput` type with a field `preferences`. The `preferences` field itself is an object containing various user preference settings. @@ -406,10 +408,11 @@ input UserProfileInput { preferences: PreferencesInput = { notifications: true, theme: "light" } } ``` + -In this example, if no value for `preferences` is provided when making a mutation, the system will automatically use the default value `{ notifications: true, theme: 'light' }`. +In this example, if no value for `preferences` is provided when making a mutation, the system will automatically use the default value `{ notifications: true, theme: 'light' }`. # Optional Properties diff --git a/website/src/docs/hotchocolate/v13/defining-a-schema/relay.md b/website/src/docs/hotchocolate/v13/defining-a-schema/relay.md index 83bf7698233..be947f19486 100644 --- a/website/src/docs/hotchocolate/v13/defining-a-schema/relay.md +++ b/website/src/docs/hotchocolate/v13/defining-a-schema/relay.md @@ -190,7 +190,7 @@ The `Serialize()` method takes the schema name as a first argument, followed by # Complex Ids -In certain situations, you may need to use complex identifiers for your data models, rather than simple integers or strings. HotChocolate provides support for complex IDs by allowing you to define custom ID types, which can be used in your GraphQL schema. +In certain situations, you may need to use complex identifiers for your data models, rather than simple integers or strings. HotChocolate provides support for complex IDs by allowing you to define custom ID types, which can be used in your GraphQL schema. ## Defining Complex ID @@ -208,7 +208,7 @@ public class Product If your `Product` model does not have an ID field, but you still want to use a complex ID for GraphQL queries, you can use a type extension. -A type extension allows you to add fields to a type that are only available within the GraphQL schema, without modifying the actual data model. +A type extension allows you to add fields to a type that are only available within the GraphQL schema, without modifying the actual data model. Here's how you can define the type extension: ```csharp diff --git a/website/src/docs/hotchocolate/v13/defining-a-schema/subscriptions.md b/website/src/docs/hotchocolate/v13/defining-a-schema/subscriptions.md index c7a6051c09a..79818654661 100644 --- a/website/src/docs/hotchocolate/v13/defining-a-schema/subscriptions.md +++ b/website/src/docs/hotchocolate/v13/defining-a-schema/subscriptions.md @@ -4,7 +4,7 @@ title: "Subscriptions"