Skip to content

Commit

Permalink
apply changes to graphql sample README
Browse files Browse the repository at this point in the history
  • Loading branch information
@DinoChiesa
DinoChiesa committed Apr 19, 2024
1 parent 2869880 commit 1618184
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 29 deletions.
46 changes: 25 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,24 +15,28 @@

## <a name="who"></a>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!
> Bear with us, please!
## <a name="intro"></a>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:

Expand All @@ -51,14 +55,14 @@ In addition, you'll find:

## <a name="using"></a>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`.

## <a name="initial"></a>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.|

Expand All @@ -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:

Expand All @@ -109,28 +113,28 @@ 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:

`chmod 744 invoke.sh`

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`


## <a name="modifying"></a>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.

## <a name="bulk"></a>Bulk deployment

Expand Down Expand Up @@ -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))
Expand All @@ -187,14 +191,14 @@ To deploy all samples and API products, run `deploy_all.sh`

## <a name="docs"></a>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
Expand Down
16 changes: 8 additions & 8 deletions sample-proxies/graphql-sample/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Run the following command to deploy both the `graphql-config` and `graphql-proxy
mvn install -Ptest -Dorg=<APIGEE_ORG> -Denv=<APIGEE_ENV> -Dusername=<APIGEE_USERNAME> -Dpassword=<APIGEE_PASSWORD>
```

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.

Expand Down Expand Up @@ -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:
Expand All @@ -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)

```
Expand Down Expand Up @@ -155,15 +155,15 @@ 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.

Scopes are filtered at the Apigee API Product level. As an example, you could have a set Apigee API Products designed like this:

![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

Expand All @@ -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.
Expand Down

0 comments on commit 1618184

Please sign in to comment.