diff --git a/README.md b/README.md index 3264ced5..ae371285 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,16 @@ ## Audience -You are an Apigee Edge API proxy developer, or you would like to learn about developing APIs that run on Apigee Edge. At a minimum, we assume you're familiar with Apigee Edge and how to create simple API proxies. To learn more, we recommend this [getting-started tutorial](https://docs.apigee.com/api-platform/get-started/get-started). +You are an Apigee Edge API proxy developer, or you would like to learn about +developing APIs that run on Apigee Edge. At a minimum, we assume you're familiar +with Apigee Edge and how to create simple API proxies. To learn more, we +recommend this [getting-started +tutorial](https://docs.apigee.com/api-platform/get-started/get-started). > These samples were built to work with Apigee EDGE. The current version of > Apigee is known as Apigee X. Most of these samples will work with Apigee X, > but the deployment scripts will not, and the instructions for administrative -> actions (eg, sign up for an account at apigee.com ) will not work either. In +> actions (eg, sign up for an account at apigee.com) will not work either. In > those cases, you will need to substitute the appropriate actions relating to > Apigee X! @@ -28,11 +32,11 @@ You are an Apigee Edge API proxy developer, or you would like to learn about dev ## Intro -This repository contains a collection of sample API proxies that you can deploy and run on [Apigee Edge](https://apigee.com/api-management/#/products). +This repository contains a collection of sample API proxies that you can deploy and run on [Apigee Edge](https://apigee.com/api-management/#/products). ![alt text](./images/sample-proxies-1.png) -The samples provide a jump-start for developers who wish to design and create Apigee Edge API proxies. Each proxy sample includes a `deploy.sh` and `invoke.sh` script. These scripts let you easily deploy and run the proxies. +The samples provide a jump-start for developers who wish to design and create Apigee Edge API proxies. Each proxy sample includes a `deploy.sh` and `invoke.sh` script. These scripts let you easily deploy and run the proxies. In addition, you'll find: @@ -51,14 +55,14 @@ In addition, you'll find: ## Using the sample proxies -Most developers begin by identifying an interesting sample based on a specific use case or need. You'll find the samples in the `./api-platform-samples/sample-proxies` folder. The Apigee doc site also has a handy [samples overview page](https://docs.apigee.com/api-platform/samples/samples-reference). +Most developers begin by identifying an interesting sample based on a specific use case or need. You'll find the samples in the `./api-platform-samples/sample-proxies` folder. The Apigee doc site also has a handy [samples overview page](https://docs.apigee.com/api-platform/samples/samples-reference). -For example, if you're interested in doing XML to JSON transformations, check out `api-platform-samples/sample-proxies/xmltojson`. +For example, if you're interested in doing XML to JSON transformations, check out `api-platform-samples/sample-proxies/xmltojson`. ## Setting up -Set up your deployment environment. +Set up your deployment environment. 1. Open the file `./api-platform-samples/setup/setenv.sh` in a text editor.| @@ -79,17 +83,17 @@ We make it easy: 1. Be sure you've updated `./api-platform-samples/setup/setenv.sh` as explained previously. -2. cd to one of the sample proxy folders in `./api-platform-samples/sample-proxies`. +2. cd to one of the sample proxy folders in `./api-platform-samples/sample-proxies`. 3. Be sure you can execute the `deploy.sh` script. For example: `chmod 744 deploy.sh` -4. Execute the deploy script. +4. Execute the deploy script. `./deploy.sh` -**Note:** If you already have the proxy deployed, the script will undeploy it first, then redeploy a new revision. +**Note:** If you already have the proxy deployed, the script will undeploy it first, then redeploy a new revision. Output like this means a successful deployment: @@ -109,7 +113,7 @@ We make this easy too! Each sample API proxy directory contains a script, `invok 1. Be sure you've updated `./api-platform-samples/setup/setenv.sh` as explained previously. -2. cd to one of the sample proxy folders in `./api-platform-samples/sample-proxies`. +2. cd to one of the sample proxy folders in `./api-platform-samples/sample-proxies`. 3. Be sure you can execute the `invoke.sh` script. For example: @@ -117,20 +121,20 @@ We make this easy too! Each sample API proxy directory contains a script, `invok 4. Open the `invoke.sh` file and take a look at the code. Basically, the invoke scripts make `curl` requests to Apigee Edge. In some cases, `invoke.sh` performs other setup tasks, such as creating products, developer apps, and other entities on Edge. - **Tip:** Always open `invoke.sh` and look through it before executing it -- this will give you valuable insight into how the API proxy is called and any setup steps that are performed. + **Tip:** Always open `invoke.sh` and look through it before executing it -- this will give you valuable insight into how the API proxy is called and any setup steps that are performed. -4. Execute the `invoke.sh` script. +4. Execute the `invoke.sh` script. `./invoke.sh` ## Modifying a sample proxy -Feel free to modify and build upon the sample proxies. You can make changes in the Edge management UI or by editing the proxy XML files locally and redeploying. Whichever approach is comfortable for you. +Feel free to modify and build upon the sample proxies. You can make changes in the Edge management UI or by editing the proxy XML files locally and redeploying. Whichever approach is comfortable for you. ->Tip: If you use Sublime for local development, check out the [Sweetlime](https://github.com/apigee/Sweetlime) project on GitHub. Sweetlime is a Sublime plugin for developing API proxies for Apigee Edge. +>Tip: If you use Sublime for local development, check out the [Sweetlime](https://github.com/apigee/Sweetlime) project on GitHub. Sweetlime is a Sublime plugin for developing API proxies for Apigee Edge. -Simply redeploy the proxies for changes to take effect. +Simply redeploy the proxies for changes to take effect. ## Bulk deployment @@ -164,7 +168,7 @@ API products, apps, and developers. ### `/setup` -Simple scripts to help you deploy the sample API proxies and profiles that they +Simple scripts to help you deploy the sample API proxies and profiles that they rely on, including API products, developers, and apps. Set you Apigee API Platform account settings in `setenv.sh` ([Register for a free Apigee account](https://docs.apigee.com/api-platform/get-started/creating-apigee-edge-account)) @@ -187,14 +191,14 @@ To deploy all samples and API products, run `deploy_all.sh` ## Apigee Edge documentation -The Apigee Edge docs are [here](https://docs.apigee.com). +The Apigee Edge docs are [here](https://docs.apigee.com). --- -Copyright © 2018 Apigee Corporation +Copyright © 2018 Apigee Corporation, 2024 Google LLC -Licensed under the Apache License, Version 2.0 (the "License"); you may -not use this file except in compliance with the License. You may obtain +Licensed under the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 diff --git a/sample-proxies/graphql-sample/README.md b/sample-proxies/graphql-sample/README.md index b2088f4b..8a6c4a09 100644 --- a/sample-proxies/graphql-sample/README.md +++ b/sample-proxies/graphql-sample/README.md @@ -45,7 +45,7 @@ Run the following command to deploy both the `graphql-config` and `graphql-proxy mvn install -Ptest -Dorg= -Denv= -Dusername= -Dpassword= ``` -Optionally, you can deploy each of the sub-modules independently by running the same command within the specific directory. +Optionally, you can deploy each of the sub-modules independently by running the same command within the specific directory. e.g. @@ -76,7 +76,7 @@ The sample Apigee proxy is designed to be simple, yet concise, in order to conve 2. **A KVM policy** to retrieve a scopes map 3. **A JavaScript policy** to convert scopes to GraphQL entitlements 4. **A JavaScript Callout** to validate and authorize the GraphQL query. - + The JavaScript Callout (in step 4), uses the [graphql-js](https://github.com/graphql/graphql-js) library to parse and syntactically validate the incoming GraphQL query. Upon validation, it proceeds to list the paths that are being accessed within the GraphQL query. For example, this query: @@ -98,7 +98,7 @@ query.resorts.name ``` In order to authorize the query, the JavaScript callout then compares the paths that are being accessed against the paths that the client is entitled to access. For a client request to be successfully authorized, the client entitlements must contain the paths being accessed in the query. - + This is what the configuration looks like for the JavaScript callout (in step 4) ``` @@ -155,7 +155,7 @@ For this sample Apigee proxy, we are building the client entitlements list by us } ``` -Given the above map, if the arriving request has `reader` scope, it means that the client is entitled to execute introspection queries as well as read resorts related data. +Given the above map, if the arriving request has `reader` scope, it means that the client is entitled to execute introspection queries as well as read resorts related data. While it's not necessary to have a scopes-to-entitlements map, it's a practical abstraction that allows you to logically group a set of entitlements and segment access to your GraphQL schema. @@ -163,7 +163,7 @@ Scopes are filtered at the Apigee API Product level. As an example, you could ha ![Products](docs/images/prods.png) -This approach plays specially well with Apigee's consumption model with OAuth, Apps, and API Products. You could enforce that subscriptions to the `GraphQL Platinum` product require approval, where as the `GraphQL Bronze` product is open to all. +This approach plays specially well with Apigee's consumption model with OAuth, Apps, and API Products. You could enforce that subscriptions to the `GraphQL Platinum` product require approval, where as the `GraphQL Bronze` product is open to all. ### Using GraphQL Playground to test the API Proxy @@ -177,13 +177,13 @@ To test the sample proxy, you can use the [GraphQL playground](https://legacy.gr As soon as the GraphQL playground opens up, it sends a couple of introspection queries to the Apigee proxy. You can open the [Apigee Trace Tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) and refresh the playground to see the introspection query arriving. - + ![Playground200](docs/images/introspect_trace.png) Note that this proxy configured such that all requests are implicitly granted the entitlements needed to introspect the schema. That's why this first request goes through successfully. -However, if you try to send additional queries, you will see that Apigee blocks them. - +However, if you try to send additional queries, you will see that Apigee blocks them. + ![Playground200](docs/images/playground_403.png) You have to open the **Headers** tab in the playground, and add a **scope** header.