Lightweight Gateway tutorial

Try the Lightweight Gateway by using the provided API definition to create a product and publish it, and then test the API.

Download the CLI toolkit and log in

For this preview, the UI is unavailable so you must work with the Lightweight Gateway using the API Connect CLI toolkit.

  1. Download the toolkit and set it up as explained in Downloading the toolkit.

  2. Log in to API Connect as explained in Logging in to the toolkit.

Create a catalog to use with this tutorial

When you create a catalog, the Lightweight Gateway is associated with it automatically.

Create a catalog using the catalog.yaml data file:

./apic -s <platform_endpoint_url> catalogs:create -o <org_name> catalog.yaml

Data file: Create a YAML file called catalog.yaml with the following content:

name: previewcatalog

Example:

  • Command:
    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com catalogs:create -o lwgw-demo catalog.yaml
  • Response:
    previewcatalog https://platform-api.us-east-a.apiconnect.test.automation.ibm.com/api/catalogs/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e80bfea1-bf1d-4af1-9d60-4fa1c16e836f

Add a TLS client profile to the provider organization

Create a TLS client profile and add it to your provider organization. The TLS client profile is used for authentication when the API is invoked.

  1. Create a TLS client profile using the tlsclientprofile.yaml file, and save the TLS_PROFILE_URL to an environment variable:
    TLS_PROFILE_URL=$(./apic -s <platform_endpoint_url> tls-client-profiles:create -o <org_name> tlsclientprofile.yaml --format json | jq '.url')

    Data file: Create a YAML file called tlsclientprofile.yaml with the following content:

    ciphers:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_128_GCM_SHA256
- ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- ECDHE_RSA_WITH_AES_256_GCM_SHA384
- ECDHE_RSA_WITH_AES_256_CBC_SHA384
- ECDHE_RSA_WITH_AES_128_GCM_SHA256
- ECDHE_RSA_WITH_AES_128_CBC_SHA256
- ECDHE_RSA_WITH_AES_256_CBC_SHA
- ECDHE_RSA_WITH_AES_128_CBC_SHA
- DHE_RSA_WITH_AES_256_GCM_SHA384
- DHE_RSA_WITH_AES_256_CBC_SHA256
- DHE_RSA_WITH_AES_128_GCM_SHA256
- DHE_RSA_WITH_AES_128_CBC_SHA256
- DHE_RSA_WITH_AES_256_CBC_SHA
- DHE_RSA_WITH_AES_128_CBC_SHA
title: httpd
name: httpd
version: 1.0.0
summary: ''
insecure_server_connections: false
server_name_indication: true
protocols:
- tls_v1.2
- tls_v1.3

    Example:

     TLS_PROFILE_URL=$(./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com tls-client-profiles:create -o lwgw-demo tlsclientprofile.yaml ---format json | jq '.url')
  2. Add the TLS client profile to the catalog using the configuredtlsclientprofile.yaml file:
    ./apic -s <platform_endpoint_url> configured-tls-client-profiles:create -o <org_name> -c <catalog_name> --scope catalog configuredtlsclientprofile.yaml

    Data file: Generate a YAML file called configuredtlsclientprofile.yaml:

    echo "{tls_client_profile_url: $TLS_URL}" > configuredtlsclientprofile.yaml

    Example:

    • Command:
      ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com configured-tls-client-profiles:create -o lwgw-demo -c previewcatalog --scope catalog configuredtlsclientprofile.yaml
    • Response:
      httpd:1.0.0   https://platform-api.us-east-a.apiconnect.test.automation.ibm.com/api/catalogs/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e80bfea1-bf1d-4af1-9d60-4fa1c16e836f/configured-tls-client-profiles/c1b1d8a8-9843-40a8-9f5e-a65f5ebcaf1e

Stage a product to the catalog

Staging a product deploys a copy of it to the target catalog without making the product visible to any developers.

Note: For this preview, you can only stage a particular product to one catalog.

Stage the product using the oai3ipProduct.yaml product file and the demo API file, and save the PRODUCT_URL in an environment variable:

PRODUCT_URL=$(./apic -s  products:publish -c <catalog_name> -o <org_name> --stage <path_to_product_yaml> --format json | jq '.url')

Data file: Create a YAML file called demo.yaml with the following content:

info:
  version: 1.0.0
  title: lwgw-product-demo
  name: lwgw-product-demo
gateways:
- lightweight-gateway
plans:
  default-plan:
    title: Default Plan
    description: Default Plan
    rateLimitMap:
      plan-limit: default
components:
  rateLimits:
    default:
    - max: 100
      intervalLen: 1
      intervalUnit: hour
apis:
  demo:
    $ref: demo.yaml
visibility:
  view:
    type: public
    orgs: []
    tags: []
    enabled: true
  subscribe:
    type: authenticated
    orgs: []
    tags: []
    enabled: true
product: 1.0.0

Data file: Create a YAML filed called lwgw-product-demo.yaml with the following content:

openapi: 3.0.2
servers:
- url: "/demo"
info:
  title: Demo
  description: Demonstrate the capabilities of the lightweight gateway
  version: 1.0.0
  x-ibm-name: demo
  x-ibm-summary: Demo API
x-ibm-configuration:
  gateway: lightweight-gateway
  compatibility:
    suppress-limitation-errors: true
  assembly:
    catch: []
    execute:
      - parse:
          documentType: json
          input: request
      - validate:
          mode: openapi-request-body
      - setVar:
          variable:
            name: arg
            value: '$header("request", "x-arg")'
      - invoke:
          output: response
          targetUrl: 'https://herald-backend/$(arg)'
          timeout: 60
          verb: keep
          tlsClientProfile: 'httpd'
      - parse:
          documentType: json
          input: response
      - validate:
          input: response
          mode: openapi-response-body
      - setVar:
          messageHeader:
            headerName: my-header-name
            messageName: response
            value: '123'
    finally: []
tags:
- name: demo
  description: good for demo purposes
paths:
  "/test":
    post:
      responses:
        default:
          description: ensure response meets schema expectations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MyResponse"
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Object"
components:
  schemas:
    Object:
      type: object
    MyResponse:
      type: object
      properties:
        headers:
          type: object
          properties:
            Format:
              type: array
              items:
                type: string
                enum:
                - simple
                - complex
        json:
          type: object
          properties:
            pet-name:
              type: string
            pet-type:
              type: string
              enum:
              - dog
              - bird

Example:

PRODUCT_URL=$(./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com products:publish -c previewcatalog -o lwgw-demo --stage  lwgw-product-demo.yaml --format json | jq '.url')

Publish the product

Publishing a product deploys a static version of the product and API to the catalog, and makes it visible to other developers who work in that catalog. After you publish the product, you can retire it from use, and then stage it to the catalog again for use in the rest of this tutorial.

Note: For this preview, you can only publish a particular product to one catalog.

Publish the product using the updatestate.yaml file:

./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog updatestate.yaml

Data file: Create a YAML file called updatestate.yaml with the following content:

state: published

Example:

./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog updatestate.yaml

Optional steps to retire and then stage the API again:

  • Retire the product using the retire.yaml file:
    /apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog retire.yaml

    Data file: Create a YAML file called retire.yaml with the following content:

    state: retired

    Example:

    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog retire.yaml
  • Stage the retired product using the staged.yaml file: 
    ./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog staged.yaml

    Data file: Create a YAML file called staged.yaml with the following content:

    state: staged

    Example:

    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog staged.yaml

Create a user

Create a user who will consume the API product. When you create a client app that calls the API in a later step, it requires a consumer organization with at least one user.

  1. List the available user registries for your provider organization:
    ./apic -s <platform_endpoint_url> user-registries:list -o <org_name>

    Example:

    • Command:
      ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com user-registries:list -o lwgw-demo
    • Response:
      previewcatalog-catalog   https://platform-api.us-east-a.apiconnect.test.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e24e1568-0f83-484d-8d1e-86376e1b26d2
sandbox-catalog          https://platform-api.us-east-a.apiconnect.test.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/243d3bc3-9afd-4d31-b698-893fe3aa0b5f
ibm-verify-test          https://platform-api.us-east-a.apiconnect.test.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/ab3e089f-20f9-4b85-b74a-448eb5ae284c
  2. Add a user to the previewcatalog-catalog registry using the user.yaml file, and save the OWNER_URL in an environment variable:
    OWNER_URL=$(./apic -s <platform_endpoint_url>  users:create -o <org_name> --user-registry <user_registry_name> user.yaml  --format json | jq '.url')

    Data file: Create a YAML file called user.yaml with the following content:

    username: johnpreview
email: john.preview@us.ibm.com
first_name: John
last_name: Preview
password: usermustchangePassw0rd!

    Example:

    OWNER_URL=$(./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com users:create -o lwgw-demo --user-registry previewcatalog-catalog user.yaml  --format json | jq '.url')
  3. List the users in the registry to verify that your new user was added:
    ./apic -s <platform_endpoint_url> users:list -o <org_name> --user-registry <user_registry_name>

    Example:

    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com users:list -o lwgw-demo --user-registry previewcatalog-catalog

    Note the URL for your new user; you will need it when you add when you create a consumer organization in the next step.

Create a consumer organization with the new user

The consumer organization contains the list of application developers who can use your APIs. When you create a consumer organization, add a user registry and the people listed in that registry become members of the new consumer organization.

Use the provided data file to create a consumer organization using the previewcatalog-catalog registry, which includes your new user John Preview.

Create a consumer organization using the previewCorg.yaml file:

./apic -s <platform_endpoint_url> consumer-orgs:create -o <org_name> -c <catalog_name> previewCorg.yaml

Data file: Generate a YAML file called previewCorg.yaml:

echo "{name: previewCorg, owner_url: $OWNER_URL, title:previewCorg}" > previewCorg.yaml

Example:

./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com consumer-orgs:create -o lwgw-demo -c previewcatalog previewCorg.yaml

Create a client app and subscribe it to the API

Create an application and subscribe it to an API. The app's credentials are verified when you call the API. You must complete the previous step to create the consumer organization before you can create an app.

For this tutorial, you will not need to set up a Developer Portal and create a full application to call the API. Instead, you can create a simple client app and call the API directly from the catalog.

  1. Create a client app using the app.yaml file:
    ./apic -s <platform_endpoint_url> apps:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> app.yaml

    Data file: Create a YAML file called app.yaml with the following content:

    name: apppreview

    Example:

    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com apps:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg app.yaml
  2. Create a subscription using the subscription.yaml file (you must create the app before you can create a subscription):
    ./apic -s <platform_endpoint_url> subscriptions:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> --app <app_name>

    Generate the data file: subscription.yaml

    echo "{product_url: $PRODUCT_URL, plan: default-plan}" > subscription.yaml

    Example:

    ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com subscriptions:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg --app apppreview subscription.yaml

Verify that your commands worked

Check the results of your commands on the gateway. This will tell you if all commands have been applied or if there some still pending.

./apic -s <platform_endpoint_url> configured-gateway-services:get -o <org_name> -c <catlog_name> --scope catalog --fields "add(gateway_processing_status,events)" <gateway_name>

Example:

 ./apic -s platform-api.us-east-a.apiconnect.test.automation.ibm.com configured-gateway-services:get -o lwgw-demo -c previewcatalog --scope catalog --fields "add(gateway_processing_status,events)" lightweight-gateway

Test the API with the Lightweight Gateway

Use curl to run some quick API calls and see how the Lightweight Gateway behaves.

Copy and run each command:

  • Bad Request - Does not parse request
    curl -v --header "Content-Type: application/json" --request POST --data '["foo", "bar"' https://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-000.apps.apic-d-j02.k93n.p1.openshiftapps.com/demo/test

    This is a bad request because the ending ] is missing from the array and the request cannot be parsed.

  • Bad Request - Does not validate request
    curl -v --header "Content-Type: application/json" --request POST --data '["foo", "bar"]' https://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-000.apps.apic-d-j02.k93n.p1.openshiftapps.com/demo/test

    This is a bad request because although the array is formatted correctly, the request schema dictates that the posted data must be a JSON object (not an array).

  • Bad Response - Does not validate response
    curl -v --header "Content-Type: application/json" --header "Format: arcane" --request POST --data '{}' https://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-000.apps.apic-d-j02.k93n.p1.openshiftapps.com/demo/test

    This is a bad response because the Format header is returned as the string arcane by httpbin.org, which does not comply with the response schema requirement that /headers/Format must adhere to the Enum constraints of simple or complex.

  • Valid Response
    curl -v --header "Content-Type: application/json" --header "Format: simple" --request POST --data '{}' https://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-000.apps.apic-d-j02.k93n.p1.openshiftapps.com/demo/test

    This is a valid response because the Format header is returned as the string simple by httpbin.org, which complies with the response schema requirement that /headers/Format must adhere to the Enum constraints of simple or complex.