GraphQL API Management with Apigee and StepZen

StepZen and Google Cloud's Apigee Enable a New Era of Full Lifecycle GraphQL API Management

GraphQL is fast emerging as a paradigm for building developer-friendly and flexible APIs. It supports application developers requesting exactly the data they want from the backend data sources. Now with both REST and GraphQL as powerful API options, API providers face the challenge of building and managing this next generation of APIs.

The integration of Apigee and StepZen technologies enables Apigee users to seamlessly connect to StepZen deployed GraphQL endpoints (no signup required on the StepZen side), and get standard API protection as well as visibility of GraphQL operations through Apigee Analytics.

Apigee + StepZen together deliver GraphQL capabilities

Apigee's new GraphQL policy lets you control traffic, enhance performance, and enforce security without requiring you to write any code or modify any backend services. By adding the GraphQL policy into a proxy created in Apigee, a developer can validate that a GraphQL query and response conforms to a specific schema, and then can chain this policy in their standard Apigee proxy pre-flow to perform other validations and management functions against that backend API.

Explore how the GraphQL Policy Works

Using a project you can clone from GitHub, which includes a GraphQL API built on StepZen, you can explore how the GraphQL policy works. The repository contains a script that makes it easy to spin up a StepZen hosted GraphQL endpoint fronted with an Apigee deployed proxy (for Apigee Hybrid or Apigee X).

Our example: eCommerce personalization

Our scenario is eCommerce personalization. Imagine an eCommerce experience that returns the city of the user and the cost, in the user's local currency, of 3 US Dollars (USD) worth of goods. In just a few steps, you can query the single GraphQL endpoint, which joins multiple APIs. The GraphQL endpoint is proxied through Apigee and therefore protected by Apigee GraphQL policies.

How does Apigee help

Apigee checks that the query conforms to the schema, ensures that the API key is valid, and collects analytics on the GraphQL call. Using Apigee's API Product and GraphQL support, you can add a quota or even restrict access to certain GraphQL operations.

This simple setup validates against a single GraphQL schema. Furthermore, by leveraging Apigee's support for flows, it is possible to have different versions of the schema available to different users. We can block requests for schemas outright while still allowing queries. Finally, we can publish access to the GraphQL endpoint in a developer portal enabling developers who consume APIs in a self-service fashion to subscribe and fetch their own unique credentials to access the new endpoint.

How does StepZen help

StepZen executes the GraphQL call against the backends. Specifically, StepZen

1. Calls api.ip-api.com to get the city, country, and currency of the user based on IP address.
2. Uses the currency information from the first call to fetch the cost of a specified amount and currency worth of goods from the currency exchange API - api.frankfurter.com - using the current exchange rate.

Here's an example GraphQL request and response that illustrates the scenario:

GraphQL Query:

{
  location(ip: "8.8.8.8") {
    city
    continent
    country
    countryCode
    priceInCountry(amount:100 from:"EUR")
  }
}

GraphQL Response:

{
  "data": {
    "location": {
      "city": "Ashburn",
      "continent": "North America",
      "country": "United States",
      "countryCode": "US",
      "priceInCountry": 114.44000000000001
    }
  }
}

Developers don't need to worry about combining those APIs themselves, and they can choose which fields they want to retrieve and therefore shape the response to suit their needs. Observe for the query above:

• Retrieves both location information and currency information in a single request.
• Calls two REST APIs to generate the appropriate response.
• The StepZen schema adds a priceInCountry field to the location response, using a currency conversion API.

Getting Started

Because both StepZen and Apigee have management APIs, you can automate creating Apigee proxies for StepZen endpoints. The repo contains an open-source utility that does this for you! It's a script that:

• autocreates a policy inside Apigee,
• creates or retrieves a StepZen account,
• deploys an endpoint to StepZen, and
• associates that endpoint with a managed API and Analytics in Apigee.

Get your environment up and running

1. Make sure that your account has sufficient privileges in Apigee to create and deploy: proxies, API Products, developers, apps, and property sets.
2. Clone the repository

   git clone git@github.com:apigee/stepzen.git

3. Change into the directory where you just cloned the repository, and run the following command:

   ./apizenSetup -o <your_org> -e <your_env> -t $(gcloud auth print-access-token) -i $(gcloud auth print-identity-token) -z

4. Though the script can take a number of optional parameters (explained in the README in the repo) by default you simply need to specify only:

   -o	your organization/project name for your apigee setup
   -e	your environment name
   -t	a gcloud token with access to deploy and create needed apigee artifacts
   -i	a gcloud generated identity token (StepZen uses this to generate a single, but unique StepZen account.)
   -z	(This is optional but if supplied the script will output your StepZen credentials. Useful if you’d like to use StepZen tooling later.)

5. The script runs through a number of steps and outputs progress along the way:
   • Calls a StepZen endpoint to fetch details of your StepZen account
   • Creates or updates an Apigee PropertySet to store your StepZen credentials
   • Deploys an Apigee API Proxy that's preconfigured with your StepZen account as a southbound target (relies on the property set configured above)
   • Create or Update Developer, API Product, and App with credentials to secure the endpoint
6. When the script finishes it displays an example curl command (see below) and shows the API Key created during the setup.
   
   If you've provided the options -z options, as suggested above, the script outputs your StepZen account, admin key, and API key. (Note those down somewhere, and keep them safe from leaking.) You may save these details as YAML (they're outputted as YAML in fact) to be used later with the StepZen tooling.

Testing the Endpoint

After the script completes you are shown an example curl command that looks something like this:

curl -X POST 'https://<apigee_environment_host>/graphql/stepzample?apikey=<APIKEY>' -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json' --compressed -d @gql-query.json

This curl command is referencing a file named `gql-query.json` that contains the same GraphQL query listed above in the example. Running this curl command yields precisely the same output listed above as well. Feel free to update the query in that file or copy it and create your own query files.

Add Google Maps to the API

For extra credit, let's add Google Maps to this API. Now our eCommerce app can show the user the closest physical store where they can pick up an order that was made online (and decide whether it is easier for them to get delivery or pickup).

1. You'll need an API key to call the Google Maps API from StepZen. Get one by following the instructions here: Getting started with Google Maps Platform
2. We have a sample schema prepared for you in the repository. StepZen Maps Sample - In this folder rename the file config.yaml.sample to config.yaml
3. Edit the config.yaml file to replace <apikey> with your key.

   configurationset:
     - configuration:
         name: google-maps
         key: <apikey>

4. Run the script with the new StepZen schema. The script should find and reuse the StepZen account which was created the previous time.

   ./apizenSetup -o <your_org> -e <your_env> -t $(gcloud auth print-access-token) -i $(gcloud auth print-identity-token) -S stepzen-maps-example -m maps

5. Now let’s test this new setup with your curl command like you did before.
   
   This time we will point to a GraphQL query stored in the `stepzen-maps-example` directory. So your new curl command looks something like this (Update the apikey and hostname for your own endpoint of course):

   curl -X POST 'https://<apigee_environment_host>/graphql/stepzample?apikey=<APIKEY>'             -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json'               --compressed -d @stepzen-maps-example-gql-query.json

The query we're executing in this case looks like the following:

query MyQuery {
  location(ip: "8.8.8.8") {
    findNearby(keyword: "Target") {
      name
      vicinity
    }
    city
    countryCode
    regionName
  }
}

What did this do?

The query looks for the nearest Target store location relative to the Lat/Long for whatever IP is returned by the initial location query for Google DNS.

This is then passed down to the embedded findNearby as lat,lon resolved from that initial lookup. StepZen then uses the Google Maps API and key that we provided to StepZen when we configured our schema.

Combining this with the ability to query for api-ip-api.com we can enhance our experience and get the closest physical store that is a Target store in a single GraphQL query. (For a minute assume that is where the pickup experience is, but feel free to try other stores.)

Learn More

StepZen's Anant Jhingran and Carlos Eberhardt sat down with Vikas Anand, chief product officer for Apigee to discuss the trends in the API economy and to demo how Google Cloud's Apigee and StepZen together enable full-lifecycle GraphQL API management. Here's the recording of that session. (Recorded March 2, 2022 | 52:00 )

Check out the Google Cloud Blog by Geir Sjurseth, Google Cloud and Carlos Eberhardt, StepZen.