Mastering Enterprise-Level GraphQL

Mastering Enterprise-Level GraphQL

• Introduction
• Prerequisites
• Business Context
• Lab Overview
• 1 - Install Node.JS
• 2 - Install IDE
• 3 - Setup StepZen
• 4 - Build your GraphQL API from a REST API
• 5 - Adding a new REST API in your GraphQL API
• 6 - Autogenerate GraphQL Schemas from MySQL Database
• 7 - Creating a composition of building blocks using @materializer
• 8 - Create a GraphQL Proxy API in APIC
• 9 - Editing and Testing the GraphQL Proxy API
• 10 - Create a Product and apply GraphQL RateLimits
• 11 - Explore the API from Developer Portal
• Summary

Lab Overview

Prerequisites

Business Context

• The application client can request only the data that it needs. For example, when retrieving bank account records, request only the account number and current balance for each account, but not the customer name and address details. With a REST API request, either the backend REST service must provide separate endpoints or parameters for different data subsets, or the application client must retrieve the complete records and then discard the unwanted data.

• The application client can retrieve multiple related resources in a single request. For example, a customer’s bank account record might include an array that references other finance products that the customer holds. If an application client wants to retrieve the bank account details for a specific customer, and details of the other finance products for that customer, then with a REST API the client would first retrieve the bank account details, and then make separate requests for each of the other products. A GraphQL API can be designed to allow the client to retrieve all this information in a single request.

Lab Overview

• 1 - Install Node.JS
• 2 - Install IDE
• 3 - Setup StepZen
• 4 - Build your GraphQL API from a REST API
• 5 - Adding a new REST API in your GraphQL API
• 6 - Autogenerate GraphQL Schemas from MySQL Database
• 7 - Creating a composition of building blocks using @materializer
• 8 - Create a GraphQL Proxy API in APIC
• 9 - Editing and Testing the GraphQL Proxy API
• 10 - Create a Product and apply GraphQL RateLimits
• 11 - Explore the API from Developer Portal

1 - Install Node.JS

1. Start your lab environment and open a browser.

2. Open the URL below (1). And download the recommended node.js version.

https://nodejs.org
Copy to clipboardCopied!

3. Save the Node installation in your machine and execute it.

4. Accept the default values and click Install to complete the installation. If necessary enter the Windows administrator password (Passw0rd).

5. When completed, just click Finish.

2 - Install IDE

1. On your browser, open the URL below (1). And download the VSCode User Installer specific of your OS (2).

https://code.visualstudio.com/Download
Copy to clipboardCopied!

3. Follow the installation steps to complete it.

4. At the end, check the option to Launch Visual Studio Code and click Finish.

5. You can close the Welcome tab.

6. Open the Terminal menu and click on New Terminal.

7. Great! Now you should see a terminal window on bottom of your Visual Studio Code. Enter the command below to check if the node installation is ok (as result of the command you should see the node version).

node -v
Copy to clipboardCopied!

8. If you are using Windows machine, now you need to change the PowerShell execution policies to be able to execute scripts in VS Code terminal. An execution policy is part of the PowerShell security strategy. Execution policies determine whether you can load configuration files, such as your PowerShell profile, or run scripts. Let’s do it! On your Visual Studio Code Terminal window run the command below.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass
Copy to clipboardCopied!

3 - Setup StepZen

1. On your terminal, run the command below to install the StepZen CLI.

npm install -g stepzen
Copy to clipboardCopied!

2. Now, let’s log in with StepZenAccount. Back to the browser window, open the URL below (1) and click on Log In link (2).

http://www.stepzen.com
Copy to clipboardCopied!

3. If you have a personal account, go ahead and log in. If you are using an account provided by your lab owner, log in with the username and password that you received.

4. On StepZen Dashboard page, on the left menu, open the Account page (key icon).

5. Here you have all the information that you need to log in using the CLI. Your Account name (1) and Admin Key (2). You will use them in the next step.

6. On your Visual Studio Code terminal window, execute the command below to log in with StepZen CLI, replace [your_account] with the account value (1) from the Account page.

stepzen login -a [your_account]
Copy to clipboardCopied!

7. Now, you need to enter your Admin Key. Copy and paste the Admin Key value (2) from the Account page.

4 - Build your GraphQL API from a REST API

• Use the command-line interface (CLI) command stepzen import curl to specify an existing REST endpoint - StepZen introspects the endpoint and auto-generates a GraphQL schema for you.
• Write your schema code in a .graphql GraphQL Schema Definition Language (SDL) file. Use the powerful GraphQL directive @rest to connect the REST endpoint, and with just a few lines of code, you have a working schema.)

1. On Visual Studio Code Terminal, execute the command below to create a new directory.

mkdir product-demo
Copy to clipboardCopied!

2. Change to the new directory.

cd product-demo
Copy to clipboardCopied!

3. You need to initialize a StepZen workspace in the current directory. Execute the command below.

stepzen init --endpoint=api/product-demo
Copy to clipboardCopied!

4. Now, let’s take advantage of StepZen to introspects the REST endpoint and auto-generates a GraphQL schema for you. Here you will use a pre-created REST API.

stepzen import curl "https://introspection.apis.stepzen.com/customers" --query-name "customers"
Copy to clipboardCopied!

5. Great, your first GraphQL API is created. Let’s explore the graphQL schema! On Visual Studio Code, click on Explorer icon (1) and click Open Folder (2).

6. Select the new created product-demo folder (1) and click Select Folder (2).

7. If necessary, click Yes, I trust the authors button.

8. To see the GraphQL schema, open the curl folder and select the index.graphql file (1). You are welcome to explore and check the .graphQL file (2).

9. If necessary, click View > Terminal to see the terminal window again.

5 - Adding a new REST API in your GraphQL API

1. Execute the command below to import another REST API.

stepzen import curl "https://introspection.apis.stepzen.com/orders" --query-name "orders" --query-type "Order"
Copy to clipboardCopied!

2. To check the new graphQL schema, open the curl-01 folder and open the new index.graphql file (1). You are welcome to explore the new schema (2).

3. Open the third schema, the index.graphql file in the product-demo folder (1) and check this schema is referencing the other two schemas (2).

4. Now, you are able to run the command below to initialize your endpoint.

stepzen start
Copy to clipboardCopied!

• Deploys the code in the current directory (or the directory provided via the —dir flag) to the specified endpoint on StepZen.
• Watches the directory for changes and automatically deploys them to the endpoint specified.
• Share a URL with StepZen’s Schema Explorer that enables you to test your API by exploring the queries and types available and querying the API running on StepZen.

5. The StepZen dashboard provides a playground for testing your GraphQL API. Let’s open it to explore our GraphQL API. Scroll down your terminal page to see the Dashboard URL of your API. Copy and paste it in you browser window.

6. In StepZen Dahsboard you can play with different queries. Go ahead and click Execute Query button (1) to test the orders query. Check the result data (2).

7. You are welcome to play with the Builder section (1), to create queries with different values. For example, delete the order query, and create a customers query with some fields (2). Execute the query again (3) and check the result data (4).

6 - Autogenerate GraphQL Schemas from MySQL Database

• Use the command-line interface (CLI) command stepzen import [mysql | postgresql] to specify your database - StepZen introspects it and auto-generates a GraphQL schema for you.
• Write your schema code in a .graphql GraphQL Schema Definition Language (SDL) file. Use the GraphQL directive @dbquery to connect the database, and with just a few lines of code, you have a working schema.)

1. Back to your terminal, cancel the current execution (CTRL+C). And execute the command below to create a GraphQL API that connects data from a database backend.

stepzen import mysql --db-host='db.introspection.stepzen.net' --db-database='introspection' --db-user='testUserIntrospection' --db-password='HurricaneStartingSample1934' --name=mysql
Copy to clipboardCopied!

2. To check the new graphQL schema, open the mysql folder and open the new index.graphql file (1). You are welcome to explore the new schema (2).

7 - Creating a composition of building blocks using @materializer

1. On the index.graphql from mysql folder (1), scroll down to see the ‘type Query’ declaration. Below the sentence ”Queries for type ‘Address’” include the query code below (2).

getAddressById(id: Int!): [Address]
@dbquery(
  type: "mysql"
  query: """
  SELECT * FROM `address` where `id` = ?
  """
  configuration: "mysql_config"
)
Copy to clipboardCopied!

2. Now open the index.graphql file from curl folder (1), this is the schema from customers REST API. Scroll down to see the ‘type RootEntry’ section. By now, the address is coming from the REST API endpoint. Let’s change it to get this value from MySQL database. Replace the current address type definition (address: Address) for the code below (2).

address: [Address]
  @materializer (query: "getAddressById")
Copy to clipboardCopied!

3. Let’s deploy the new API. And refresh the StepZen Dashboard.

stepzen start
Copy to clipboardCopied!

4. On the StepZen Dashboard page, use the Builder section (1), to create a customers query including address attributes (2). Execute the query again (3) and check the result data is coming from Rest and MySQL database (4).

5. Before you move to APIC section, take a copy of your API endpoint (1) and the Authorization header (2). You will need them later to invoke your API.

• API Keys: You can use API keys to control access to the entire endpoint. API keys are the default access control mechanism.
• Field Policies: You can use Field policies to control access to specific entry point fields on the endpoint. Field policies provide fine-grained access control to your GraphQL API, using a model similar to attribute-based access control.

8 - Create a GraphQL Proxy API in APIC

1. If you received a lab account from your lab monitor, you need to open your email inbox to get your APIC environment URL. On your inbox (log in with your lab user and password), search for IBM SaaS (1), open the ”Your API Connect trial is ready” email (2).

2. Now, click Access trial button.

3. Log in with your APIC user and password (same user and password received from your lab monitor or using the account that you created).

4. Here, you are on your API Connect Enterprise as a Service environment. API Connect Enterprise as a Service is a cloud-based edition of IBM API Connect. Using API Connect Enterprise as a Service enables you to work in the cloud to create, manage, secure, and socialize APIs using our latest user experiences, innovation, and industry standards for full API lifecycle management.

   API Connect Enterprise as a Service uses software-as-a-service as a delivery model. With this model, API Connect is hosted on Amazon Web Services and is managed by IBM. You pay for using the software without worrying about owning and maintaining the underlying infrastructure. With API Connect Enterprise as a Service, you pay for usage through your AWS bill.

   Let’s see how to create a GraphQL Proxy API. Click on the Develop menu.

5. Then click Add->API.

6. To create a GraphQL proxy, select From Existing GraphQL service (GraphQL proxy) (1). When you point to an existing GraphQL server, API Connect introspects the service and automatically creates a GraphQL proxy service. Then click Next (2).

7. Enter the following values:

   Title: customers (1) GraphQL server URL: [Your API URL copied from StepZen Dashboard] (for example: https://wanaka.stepzen.net/api/product-demo/__graphql) (2)

8. As described earlier in this lab, your StepZen API is using an API Key approach to control access to the entire endpoint. Because of that, you need to include the API Key in the Authorization Header of the HTTP Header. Here you will include that to read the API Schema for introspection to setup this proxy API, and it will be used this one time only and not be saved for later to call the API itself. Let’s do it!

   In the HTTP Header section, click Add (1) to enter Authorization (2) as Header and paste the API Key value that you copied from the StepZen Dashboard Headers section as Value (3). Then click Next (4).

9. The schema validator reports warning and errors if found. Ignore the Schema warning by now, will fix this warning in later steps. In the Paths section, select all the available endpoints (1), then click Next (2).

10. Keep both Secure using Client ID and CORS checked (1) and click Next (2).

11. Great! API Connect successfully created a GraphQL proxy API.

9 - Editing and Testing the GraphQL Proxy API

1. Now, let’s edit the API to view more details on the proxy API just created. Click Edit API to continue.

2. GraphQL APIs are structured the same as REST APIs with some additional options. Just like REST APIs, you will be able to add security schemas, paths and definitions from the left menu bar. You can also view the Gateway, Test and Explorer tabs similar to REST APIs. You will notice a new tab for GraphQL APIs. Click on GraphQL Schema tab to view the schema.

3. The GraphQL Schema tab displays Type for every type in your GraphQL schema, and Type Weight information for the cost or expense of each type. The weighting factor is used when calculating the type cost for a request to the GraphQL API. For example, a field that requires extensive CPU or memory use on the server to retrieve its value would be given a higher cost. Click View in the Warning message.

4. In addition to the warning details, the Warning window gives an option to fix the warning by applying the limits. While this Artificial Intelligence is often very accurate, for a real scenario it is important to carefully examine the results and only accept them when they are accurate, since this affects the security of your application. In our case, click Apply all (1), then click Apply (2).

5. After applying the recommendations, the warning message is removed. Click Save to save the API definition .

6. Now, let’s open the Gateway view.

7. The flow is automatically created as part of the initial API creation. You may apply additional logic by dragging and dropping items from the palette to the canvas. Let’s do a small change to allow Authorization header propagation. Scroll down the flow (1) and on the Otherwise ramification (2), you should see a graphql-invoke node, click on it to edit (3).

8. On the graphql-invoke node definition, scroll down to see the Header control section. Click on Add allowlist to add a new header in the list.

9. Enter Authorization as the new header allowed (1) and click Save button (2). This means that we will send the Authorization header on to the backend.

10. Now, let’s test the API. To publish the API toggle the button from offline to online.

11. After successfully publishing the API to API Gateway, additional tabs appear on the screen. Select Test tab to test the API.

12. The Test feature also includes a GraphQL Editor. Enter the following GraphQL query in the GraphQL Editor. It is not JSON, but looks somewhat similar to the JSON that will come back as the response. You may use Prettify option to improve the visualization of the GraphQL query.

{
  customers {
    email
    id
    name
    address {
      city
      countryRegion
      postalCode
Copy to clipboardCopied!

13. Now you need to include the Authorization heard. Open the Parameters tab.

14. Everytime that you invoke your API you need to pass your API Key as the Authorization header. So let’s include it in our test. On the bottom of the Parameters list, include a new parameter with the following value:

    Key: Authorization (1) Located In: header (2) Value: [paste the API Key value that you copied from the StepZen Dashboard Headers] (3)

15. Now click the Send button (1) and open the GraphiQL tab (2) again to see the result.

16. On the Trace section, you should see an HTTP Status: 200 (1) and in the Response data you have the data returned from your GraphQL API (2).

17. Great, but you can simplify it, by hard coding the Authorization header parameter in your GraphQL API Proxy flow. Let’s do it! Open the Gateway tab again.

18. On the Otherwise (1) which starts with a Parse, you will add a node before the graphql-invoke node. On the Palette view, scroll down to see the Policies section (2). Drag and drop the Set Variable (3) node between the ”ratelimit expected” node and the ”graphql-invoke” node (4).

19. Enter set-authorization as Title (1) and click Add action (2).

20. Keep Set (1) as the type of the action. On the Set field, enter message.headers.Authorization (2) as the name of the variable to be set. Select String (3) as type of the value to set. And in the Value field, paste the API Key value that you copied from the StepZen Dashboard Headers (4).

21. Then click Save.

22. Let’s test our API again, this time without passing the Authorization token. Open the Test tab (1), and click the Execute Query button (2). (Note: if you want, you can check in the Parameters tab that there isn’t an Authorization header parameter).

23. Great! Now your GraphQL Proxy is running and available to be used. You are welcome to change the GraphQL query to test more scenarios. You can also use the Example button to help start your creativity. Next section you will learn how to create a product to apply GraphQL RateLimits. On breadcrumbs, return to Develop page.

10 - Create a Product and apply GraphQL RateLimits

1. Click Add->Product.

2. Select New product (1) and click Next (2).

3. Name the product as Customers Product (1) and click Next (2).

4. Add Customers API to the product by selecting customers (1). Then click Next (2).

5. The Default Plan contains traditional rate limiting options, but in the next steps, you will be able to list GraphQL Rate Limits. For now, just click Next.

6. Publish the Product to Sandbox Catalog by selecting Publish product (1). Accept the default for Visibility and Subscribability (2) and click Next (3).

7. Great! You have your new product. Click Done.

8. Back to the Develop view, open Products tab (1) and click on Customers Product (2).

9. Open the Plans section (1), and on the Default Plan, open the context menu (2) and select Edit (3).

10. Scroll down, and now you can see the GraphQL rate limits. You will be able to adjust GraphQL cost parameters from this section (including costs per field or type). You can set a limit or make it unlimited. In this tutorial, you will not be making any changes.

    If you want to understand how the GraphQL rate limits work, check this documentation page.

11. On the left menu, click Manage icon to manage our Sandbox catalog.

11 - Explore the API from Developer Portal

1. Let’s get our Portal URL. On Manage page, open the Sandbox catalog.

2. Click Catalog settings (1) and open the Portal tab (2).

4. This Developer Portal is your public-facing website and therefore it is highly flexible and customizable, but we’ll be using the default design. Note that all of these next steps are simulating what your API Consumer, your end-user customer, will do to find, buy, and use your API. Click Create account to create a new developer account.

5. Complete the registration form, go ahead and use any personal email. Take note of the username (not email) and password. You will need them later to log in to the Developer Portal.

6. You will receive an email to activate your new developer account. Click on the link to validate the registration.

7. Sign in (1) to Developer Portal using your developer’s username and password (2).

8. Developer Portal displays all the products that are currently published. In your case, no Apps created yet. As a consumer/developer, we’re going to create a new application in the portal. This will give us an API key, allowing us to call our APIs. Click Create a new App.

9. Enter Consumers Application as the App Title (1). Click Save (2).

10. On the Credentials dialog box, copy the API Key (1), copy the API Secret (2), then click OK (3).

11. You have not subscribed to any APIs, so let’s do it now. Click on Why not browse the available APIs? link.

12. Click on Customers Product 1.0.0.

13. In the Default Plan section, click Select.

14. Select the Consumers Application.

15. Confirm the subscription by clicking Next.

16. Click Done.

17. You are now back at the product screen. Let’s explore your API here. Click the customers 1.0.0 API.

19. Paste the API Key that you copied in the previous step (1). Paste the GraphQL below in the GraphQL editor (2). And click on Execute Query button (3).

{
  customers {
    email
    id
    name
    address {
      city
      countryRegion
      postalCode
Copy to clipboardCopied!

20. Great! Your GraphQL Proxy API is running and available for your ecosystem. You are welcome to continue to test the API, using the GraphQL Editor. Submit requests with different field names and watch how quickly the results are returned in the results window. If this was a REST API multiple end points would be needed to achieve the same result.

21. That was the experience as the API Consumer, your paying customer. Now we return to your experience as an API Provider with an API that is being called, and you have analytics information about the usage of the application. Open the Apps page (1) and select the Consumers Application (2).

22. In this page, the developers can view information and insights about the application.

Summary