[Tutorial] WSO2 API Microgateway - Secured proxy petstore service + Docker (MacOS)

What is this WSO2 API Microgatway?

"The WSO2 API Microgateway is a lightweight message processor for APIs. The API Microgateway is used for message security, transport security, routing, and other common API Management related quality of services. It can process incoming and outgoing messages while collecting information required for usage metering and throttling capabilities. The API Microgateway natively supports scaling in highly decentralized environments including microservice architecture. An immutable, ephemeral Microgateway fits well with the microservice architecture. The API Microgateway is also capable of operating in lockdown environments such as IoT devices since connectivity from the API Microgateway to the API Management system is not mandatory."

In summary, WSO2 API Microgateway is a lightweight gateway distribution that can be used to deploy a single API or multiple APIs, i.e. WSO2 API Microgateway is a specialized form of WSO2 API Gateway.

In this use case let's see how a service can be securely proxied via WSO2 API Microgateway 3.1.0. Let's expose the publicly available petstore services (https://petstore.swagger.io/v2/ ) using the microgateway.

This use case is carried on the following environment.

1. OS: macOS Catalina V10.15.3
2. JAVA: Java(TM) SE Runtime Environment (build 1.8.0_162-b12)

Consider the following installation prerequisites.

1. Docker - Mine was docker desktop community: V2.2.0.3 (42716) stable channel
1. If you already don't have docker installed, please follow [1] and install.
2. Once you have completed installation run docker for desktop and in terminal, run docker info and check status.
2. WSO2 API Microgateway toolkit - Mine was V3.1.0 latest release at the time of writing this article.
1. Go to https://wso2.com/api-management/api-microgateway/ and download TOOLKIT -> MacOS Zip Archive
2. Extract it do a location of your choice and lets call it <MGWTK_HOME>
   e.g. /Users/Shared/wso2/packs/wso2am-micro-gw-toolkit-macos-3.1.0
3. Append the full path including /bin to PATH environment variable as follows.
1. With Catalina upgrade now most of you are using ~/.zprofile [2] to maintain your PATH variables. Add following two lines to this file.
   export MGWTK_HOME=/Users/Shared/wso2/packs/wso2am-micro-gw-toolkit-macos-3.1.0
   export PATH=$MGWTK_HOME/bin:$PATH
2. Run source ~/.zprofile to refresh the changed zprofile file.
4. Run micro-gw version
   
   JAVA_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0_162.jdk/Contents/Home
   3.1.0
   
   

Now let's begin.

1. Navigate to your workspace directory of your choice.
2. Using famous online petstore API definition lets initialize petstore project as follows.
   micro-gw init petstore -a https://petstore.swagger.io/v2/swagger.json
   
   JAVA_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0_162.jdk/Contents/Home
   Project 'petstore' is initialized successfully.
   
   
   (Use "micro-gw build petstore" after copying the api definitions)
   (Use "micro-gw import petstore [-l]|[-a -v]" to import APIs from WSO2 API Manager)
3. Using tree command [3] check the newly created directory structure as follows.
   
   user % tree
   .
   └── petstore
       ├── api_definitions
       │   └── swagger.json
       ├── conf
       │   └── deployment-config.toml
       ├── extensions
       │   ├── extension_filter.bal
       │   ├── startup_extension.bal
       │   └── token_revocation_extension.bal
       ├── grpc_definitions
       ├── interceptors
       ├── lib
       └── policies.yaml
4. Now build the project and the docker image as follows.
   micro-gw build petstore --docker --docker-image petstore:v1 --docker-base-image wso2/wso2micro-gw:3.1.0-alpha
   You can see the following output.
   
   JAVA_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0_162.jdk/Contents/Home
   Generating sources...[DONE]
   
   
   ..................................
   There are no new updates available
   ..................................
   Compiling source
   wso2/petstore:3.1.0
   
   
   Creating balos
   target/balo/petstore-2019r3-java8-3.1.0.balo
   
   
   Running tests
   wso2/petstore:3.1.0
   No tests found
   
   
   
   
   Generating executables
   target/bin/petstore.jar
   
   
   Generating docker artifacts...
   @docker  - complete 2/2 
   
   
   Run the following command to start a Docker container:
   docker run -d petstore:v1
   
   
   
   
   BUILD SUCCESSFUL
   Target: /Users/Shared/wso2/testbed/microgw-3.1.0/petstore/target/petstore.jar
5. Now let's expose this petstore API via WSO2 API Microgateway Docker image as follows.
   docker run -d -p 9090:9090 -p 9095:9095 petstore:v1
   
   
   105edc5b762c767a3c8ddf2637754698bd3fa26527d7c7f3c25dafc05ba7f25c
   
   Run following command to check just to the newly created image for yourself.
   docker images
   
   REPOSITORY                     TAG                 IMAGE ID            CREATED              SIZE
   petstore                       v1                  34a5cb70edda        About a minute ago   288MB
   wso2/wso2micro-gw              3.1.0-alpha         8a050f202d8d        7 weeks ago          250MB
   wso2/micro-integrator          1.1.0               088477c689f6        6 months ago         315MB
6. Invoking the API resource.
1. Consider API resource pet/{petId}. As you can see in  https://petstore.swagger.io/v2/swagger.json, this resource is secured using an API Key in api_key header as follows.
   
   paths:
     '/pet/{petId}':
       get:
         security:
         - api_key: []
   securityDefinitions:
     api_key:
       type: apiKey
       name: api_key
       in: header
   Therefore let's obtain a token which will be used to invoke this API.

   TOKEN=$(curl -X get "https://localhost:9095/apikey"
   -H "Authorization:Basic YWRtaW46YWRtaW4=" -k)

     % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                    Dload  Upload   Total   Spent    Left  Speed

   100   621    0   621    0     0   2171      0 --:--:-- --:--:-- --:--:--  2171

   
   

   You can checkout the token as follows.

   echo $TOKEN

   eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJqd3QiLCAia2lkIjoiYmFsbGVyaW5hIn0.eyJzdWIiOiJhZG1pbiIsICJpc3MiOiJodHRwczovL2xvY2FsaG9zdDo5MDk1L2FwaWtleSIsICJpYXQiOjE1ODY0MTYxNzgsICJqdGkiOiIzMjUxYTQ3OC1kYWFiLTQ2OTQtYTIzYi04NWMyYmZiYThmYjciLCAia2V5dHlwZSI6IlBST0RVQ1RJT04iLCAiYWxsb3dlZEFQSXMiOltdfQ.PJCB_XuY6F_Ph-NoMNlZRcrnXdk9-Dfflc49MRETjnzL6Z7Wyg6w4iyeNwmGkHhqk2SUqoOmZ7ZucT7ZmLMCe_ejoPVXTmvX9QtnF8gab3zE1Ww4yA8sVzCNVJWXQiPzkoiJ4yPX-e6CxEzluYQJLbL9H8icP9xpkTcck7kLo-vNqsT3gylQPBn39ZQnaFwkJeX1gFRi6G3-MwgPQhU2vRT1NAWCZdrYjPX0JB1BG_KOYUgWAbkc66UJBGgj0-b8_8eYoJ2_AmWlYEWEmpb8iK-BY6pTjYcFAEOB6Q28K-QglVSBkdTa-tQCfYkN9enJwFhd4Mr6_3pHcxQrgZ71xA
2. Now using this newly obtained token stored in TOKEN variable let's invoke the API resource as follows. Note that I have piped json_pp at the end to pretty print json response [3].
   curl -X GET "https://localhost:9095/v2/pet/1" -H "accept: application/json" -H "api_key:$TOKEN" -k  | json_pp
   

     % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                    Dload  Upload   Total   Spent    Left  Speed

   100   201    0   201    0     0    152      0 --:--:--  0:00:01 --:--:--   152

   {

      "status" : "available",

      "photoUrls" : [

         "img/test/dog.jpeg",

         "img/test/dog1.jpeg"

      ],

      "id" : 1,

      "category" : {

         "name" : "Animal",

         "id" : 1001

      },

      "tags" : [

         {

            "name" : "Pet",

            "id" : 2001

         },

         {

            "name" : "Animal",

            "id" : 2002

         }

      ],

      "name" : "doggie"

   }

You have completed this tutorial.

For more information on WSO2 API Microgateway and documentation please follow the link below.

https://docs.wso2.com/display/MG310/Getting+Started

References:

[1] https://docs.docker.com/docker-for-mac/install/

[2] https://superuser.com/questions/866683/iterm-zsh-not-reading-bashrc-or-bash-profile

[3] https://til.hashrocket.com/posts/pgyjvtuwba-pretty-print-json-responses-from-curl