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.

Warning: The Lightweight Gateway preview currently supports only HTTP. Do not use this environment for production workloads.

Download the CLI toolkit and log in

This tutorial can be done by using either the UI or API Connect CLI toolkit. The following instructions are for the toolkit.

Download the toolkit and set it up as explained in Downloading the toolkit.
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 by 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.automation.ibm.com catalogs:create -o lwgw-demo catalog.yaml

Response:

previewcatalog https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/catalogs/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e80bfea1-bf1d-4af1-9d60-4fa1c16e836f

Enable the Lightweight Gateway services in the catalog. For more information, see ../com.ibm.apic.apionprem.doc/create_env.html.

Add a TLS client profile to the proPreviewcOrg.yamlvider 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.

Create a TLS client profile by 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 -r '.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.automation.ibm.com tls-client-profiles:create -o lwgw-demo tlsclientprofile.yaml ---format json | jq -r '.url')

Add the TLS client profile to the catalog by 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_PROFILE_URL}" > configuredtlsclientprofile.yaml

Example:

Command:

./apic -s platform-api.us-east-a.apiconnect.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.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 stage only a particular product to one catalog.

Stage the product by using the lwgw-product-demo.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 -r '.url')

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

Note: This file is the OpenAPI definition that describes the API you publish and test by using the Lightweight Gateway.

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:
          input: request
          request:
            schema:
              validateSchema: true
      - set:
          variable:
            name: arg
            value: '$header("request", "x-arg")'
      - invoke:
          output: response
          endpoint:
            http:
              target:
                url: https://httpbin.org/anything
                tlsClientProfile: httpd:1.0.0
                timeout: 60
      - parse:
          documentType: json
          input: response
      - validate:
          input: response
          request:
            schema:
              validateSchema: true
      - set:
          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

Note: The targetUrl field that is previously used in the demo.yaml code sample is still supported for this technology preview but will not be supported at the general release. The code sample now uses the endpoint field.

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

Note: This file is the product definition file, which defines the API product that bundles one or more APIs (like the one in demo.yaml).

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

Example:

Note: Now, your API and product is defined. The following command is to stage the product to the catalog. Staging prepares the product for publishing but does not yet make it visible to developers.

PRODUCT_URL=$(./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com products:publish -c previewcatalog -o lwgw-demo --stage  lwgw-product-demo.yaml --format json | jq -r '.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 publish only a particular product to one catalog.

Note: The PRODUCT_URL variable that you set during the staging step is not used in the publishing step. You use this variable later when you create a subscription for a client application.

Publish the product by 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.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 by 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.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog retire.yaml

Stage the retired product by 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.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 consumes 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.

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.automation.ibm.com user-registries:list -o lwgw-demo

Response:

previewcatalog-catalog   https://platform-api.us-east-a.apiconnect.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.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.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/ab3e089f-20f9-4b85-b74a-448eb5ae284c

Add a user to the previewcatalog-catalog registry by 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.automation.ibm.com users:create -o lwgw-demo --user-registry previewcatalog-catalog user.yaml  --format json | jq '.url')

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.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 who are listed in that registry become members of the new consumer organization.

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

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

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

Create a consumer organization by using the previewCorg.yaml file:

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

Example:

./apic -s platform-api.us-east-a.apiconnect.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. 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.

Create a client app by 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.automation.ibm.com apps:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg app.yaml

Create a subscription by 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

Note: This commend identifies the staged product to which the client application subscribes.

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

Example:

./apic -s platform-api.us-east-a.apiconnect.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 tells 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.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:

Note: The endpoint must include your catalog name, product name, and provider organization name in the following format: http://{product}-{catalog}-{org}.{gateway_name}.rosa.apic-v-lw01.lugt.p3.openshiftapps.com/{version}/{server_url}/{path}

Bad Request - Does not parse request

curl -v --header "Content-Type: application/json" --request POST --data '["foo", "bar"' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/demo/test

This request 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"]' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/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).

Valid Response
```
curl -v --header "Content-Type: application/json" --header "Format: simple" --request POST --data '{}' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/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.