All docs This doc
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

The API Microgateway Toolkit

The API Manager Microgateway Toolkit is a specialized form of the WSO2 API Gateway. Its main characteristics are:

  • The ability to execute in isolation without mandatory connections to other components (Key Manager, Traffic Manager, etc).
  • The ability to host only a subset of specific APIs (defined in the API Publisher) instead of all.
  • Immutability; if you update an API, you need to re-create the container/instance and hot deployment is not possible.

Microgateway offers you a proxy that is capable of performing security validations (OAuth, Signed JWT), in-memory (local) rate limiting and operational analytics.

Setting up the API Microgateway Toolkit

  1. Download the Microgateway ToolKit distribution and extract it.
  2. Append the full path of the /bin folder of the extracted Microgateway ToolKit distribution to the PATH environment variable.

Generating a distribution for a single API

It is possible to create a microgateway distribution for a single API. The API needs to be in Published state.

  1. Navigate to the API Publisher (https://<hostname>:9443/publisher). Sign in using admin as the username and password. 
  2. Deploy the sample Pizzashack API by clicking Deploy Sample API
  3. Navigate to a preferred workspace folder using the command line. This location will be used to run micro-gw commands and will be used togeneratemicrogatewayartifacts.
  4. Setup a project using the below command.

    micro-gw setup <project name> -a <API name> -v <version>

    Use "admin" when the tool requests the username and password. Keep the other parameters as default by pressing Enter. 

    Here is an example:

    $ micro-gw setup pizzashack-project -a PizzaShackAPI -v 1.0.0
    
    BALLERINA_HOME environment variable is set to /home/user/wso2am-micro-gw-toolkit-2.5.0-beta2/lib/platform
    MICROGW_TOOLKIT_HOME environment variable is set to /home/user/wso2am-micro-gw-toolkit-2.5.0-beta2
    Enter Username: 
    admin
    Enter Password for admin: 
    
    Enter APIM base URL [https://localhost:9443/]: 
    
    Enter Trust store location: [lib/platform/bre/security/ballerinaTruststore.p12]
    
    Enter Trust store password: [ use default? ]
    
    Setting up project pizzashack-project successful.

    From the above command, the tool will connect with API Manager REST APIs and retrieve the API which was specified above. The source artifacts will be generated in the current folder location.

    The folder structure will look similar to the following,

    .
    └── pizzashack-project
        ├── conf
        │   └── label-config.toml
        ├── src
        │   ├── endpoints.bal
        │   ├── extension_filter.bal
        │   ├── PizzaShackAPI_1_0_0.bal
        │   └── policies
        │       ├── application_10PerMin.bal
        │       ├── application_20PerMin.bal
        │       ├── ...
        │       └── throttle_policy_initializer.bal
        └── target

    If you rerun the setup command while you already have a project named with pizzashack-project in the current working directory, you will get an error like below.

    $ micro-gw setup pizzashack-project -a PizzaShackAPI -v 1.0.0
    
    [micro-gw: Project name `pizzashack-project` already exist. use -f or --force to forcefully update the project directory., Run 'micro-gw help' for usage.]


    As suggested in the above output, if you need to override the current project, you need to run the setup command with -f (--force)option.

    $ micro-gw setup pizzashack-project -a PizzaShackAPI -v 1.0.0  -f
    
    Enter Password for admin: 
    
    Setting up project pizzashack-project is successful.
  5. Build the microgateway distribution for the project using the following command:

    micro-gw build <project name>

    Here is an example:

    $ micro-gw build pizzashack-project
    
    BALLERINA_HOME environment variable is set to /home/user/wso2am-micro-gw-toolkit-2.5.0-beta2/lib/platform
    MICROGW_TOOLKIT_HOME environment variable is set to /home/user/wso2am-micro-gw-toolkit-2.5.0-beta2
    Build success

    Once the above command is executed, the generated source files are built and a Microgateway distribution is created under the target folder. 

    The name of the distribution will have the format micro-gw-<project name>.zip. For the above example, the name will be micro-gw-pizzashack-project.zip.

  6. Next, unzip the micro-gw-pizzashack-project.zip and run the gateway shell script inside the bin folder of the extracted zip using the following command:

    bash gateway

    The Microgateway will now start for the Pizzashack API. 

    micro-gw-pizzashack-project/bin$ bash gateway
    
    ballerina: HTTP access log enabled
    ballerina: initiating service(s) in '/home/user/workspace/pizzashack-project/target/micro-gw-pizzashack-project/exec/pizzashack-project.balx'
    2018-06-29 21:16:44,142 INFO  [wso2/gateway:0.0.0] - Subscribing writing method to event stream 
    ballerina: started HTTPS/WSS endpoint 0.0.0.0:9096
    ballerina: started HTTPS/WSS endpoint 0.0.0.0:9095
    ballerina: started HTTP/WS endpoint 0.0.0.0:9090

Generating a distribution for a group of APIs

It is possible to create a microgateway distribution for a group of APIs. For grouping APIs, a label needs to be created and attached to the APIs those need to be in a single group.

Creating and attaching a Microgateway to an API

  1. Log in to the Admin portal ( https://<hostname>:9443/admin). Use admin as the username and password. 

  2. To add a new Microgateway label, click LABELS under MICROGATEWAY, and then click ADD MICROGATEWAY.
  3. Create a new label (e.g. MARKETING_STORE), add a host (e.g. https://localhost:9095) and click Save.


  4. Navigate to the API Publisher (https://<hostname>:9443/publisher). Sign in using admin as the username and password. 
  5. Deploy the sample Pizzashack API by clicking Deploy Sample API if you have not already done.
  6. Choose to edit the created Pizzashack API.

  7. Navigate to the Manage section and click Gateway Environments

  8. Select the newly created label to attach it to the Pizzashack API.
  9. Click  Save & Publish.
  10. Similarly, you can select MARKETING_STORE label for few other Published APIs.

Generating a Microgateway distribution

  1. Run the initial setup command for the MARKETING_STORE label after navigating to a preferred workspace folder.

    micro-gw setup <project name> -l <label name> 

    Here is a sample:

    micro-gw setup marketing_project -l MARKETING_STORE 
  2. Build the microgateway distribution for the project using the following command:

    micro-gw build marketing_project

    Once the above command is executed, the generated source files are built and a Microgateway distribution is created under the target folder.

  3. Next, unzip the micro-gw-marketing-project.zip and run the gateway shell script inside the bin folder of the extracted zip using the following command:

    bash gateway 

    The Microgateway starts for the APIs grouped with MARKETING_STORE label you just created. 

    micro-gw-marketing-project/bin$ bash gateway
    
    ballerina: HTTP access log enabled
    ballerina: initiating service(s) in '/home/user/workspace/marketing-project/target/micro-gw-marketing-project/exec/marketing-project.balx'
    2018-06-29 21:16:44,142 INFO  [wso2/gateway:0.0.0] - Subscribing writing method to event stream 
    ballerina: started HTTPS/WSS endpoint 0.0.0.0:9096
    ballerina: started HTTPS/WSS endpoint 0.0.0.0:9095
    ballerina: started HTTP/WS endpoint 0.0.0.0:9090
    
    

Viewing Microgateway details in the API Store

  1. Log in to the API Store ( https://<hostname>:9443/store). Use admin as the username and password.
  2. Any attached Microgateways are shown in the Overview tab of the API.

Invoking the API

Once you start the microgateway, you can use a JWT or an OAuth2 token to invoke the API. For the invocation URL, you can use either https://localhost:9095 (HTTPS) or http://localhost:9090 (HTTP). 

Using a signed JWT token

A signed JWT token is a self-contained access token which can be validated by the microgateway itself without connecting to any external party. In contrast, a typical OAuth2 token needs to be validated by connecting to the Key Manager. This is one of the key advantages of the microgateway, if you need to run it in offline mode.

  1. To invoke the API using a JWT token, you need to have an application created in the Store with a JWT token type. Edit an existing application or create a new application in the API Store, and set the token type to JWT.

  2. Click Regenerate to generate a JWT token, instead of an OAuth2 access token. 
  3. Invoke the API using the JWT token. A sample cURL command is given below.

    curl -k -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IlVCX0JReTJIRlYzRU1UZ3E2NFEtMVZpdFliRSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoxLCJuYW1lIjoiRGVmYXVsdEFwcGxpY2F0aW9uIiwidGllciI6IlVubGltaXRlZCJ9LCJzY29wZSI6ImFtX2FwcGxpY2F0aW9uX3Njb3BlIGRlZmF1bHQiLCJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0OjgyNDNcL3Rva2VuIiwia2V5dHlwZSI6IlBST0RVQ1RJT04iLCJzdWJzY3JpYmVkQVBJcyI6W3sibmFtZSI6IlBpenphU2hhY2tBUEkiLCJjb250ZXh0IjoiXC9waXp6YXNoYWNrXC8xLjAuMCIsInZlcnNpb24iOiIxLjAuMCIsInB1Ymxpc2hlciI6ImFkbWluIiwic3Vic2NyaXB0aW9uVGllciI6IlVubGltaXRlZCIsInN1YnNjcmliZXJUZW5hbnREb21haW4iOiJjYXJib24uc3VwZXIifV0sImV4cCI6MTUyODgwMjg3ODExMCwiaWF0IjoxNTI4ODAyODgwMTEwLCJqdGkiOiJlZmQxZGVhZC1iNWI3LTQ0M2MtOTIyMC1iYzJjZTJjY2MwYjEifQ==.b8P2uPRkVai0O7PcbvbjANLuHlJQzX1eHplweDpE6ItbEHRTkN2U_h6b39tz14dKUmigzASinj5LheUWGB7gEDRqlc39ckhRX2qpolQpITZvpzYo8ky9AcxlJXLxrfPwgdht36zfIQwlPN_s2A5nY7c9pDBMu0OOOlYpmK81SrtipFSTAyPiRg5VyY3n-4POnjkEF-LQKCCTq7ef0uLOFTcoCT-gqNsXeKqt15suCYj5QMHJ8VP5bKsKZy9-1o9oFNlwc1QE0qE01fPuGuz-4J22OvkHyrasbjhhGaaDgdpdERl9ElUDuL0C9AdX6Fb1sz54gnAiU3RUBK3RQUDK7Q==" https://localhost:9095/pizzashack/1.0.0/menu

    You receive a response similar to the following:

    HTTP/1.1 200 OK
    Date: Sat, 30 Jun 2018 04:18:12 GMT
    Content-Type: application/json
    Transfer-Encoding: chunked
    server: WSO2 Carbon Server
    
    [{"name":"BBQ Chicken Bacon","description":"Grilled white chicken, hickory-smoked bacon and fresh sliced onions in barbeque sauce","price":"13.99","icon":"/images/6.png"},{"name":"Chicken Parmesan","description":"Grilled chicken, fresh tomatoes, feta and mozzarella cheese","price":"9.99","icon":"/images/1.png"},{"name":"Chilly Chicken Cordon Bleu","description":"Spinash Alfredo sauce topped with grilled chicken, ham, onions and mozzarella","price":"17.99","icon":"/images/10.png"},{"name":"Double Bacon 6Cheese","description":"Hickory-smoked bacon, Julienne cut Canadian bacon, Parmesan, mozzarella, Romano, Asiago and and Fontina cheese","price":"16.99","icon":"/images/9.png"},{"name":"Garden Fresh","description":"Slices onions and green peppers, gourmet mushrooms, black olives and ripe Roma tomatoes","price":"9.99","icon":"/images/3.png"},{"name":"Grilled Chicken Club","description":"Grilled white chicken, hickory-smoked bacon and fresh sliced onions topped with Roma tomatoes","price":"13.99","icon":"/images/8.png"},{"name":"Hawaiian BBQ Chicken","description":"Grilled white chicken, hickory-smoked bacon, barbeque sauce topped with sweet pine-apple","price":"27.99","icon":"/images/7.png"},{"name":"Spicy Italian","description":"Pepperoni and a double portion of spicy Italian sausage","price":"13.99","icon":"/images/2.png"},{"name":"Spinach Alfredo","description":"Rich and creamy blend of spinach and garlic Parmesan with Alfredo sauce","price":"27.99","icon":"/images/5.png"},{"name":"Tuscan Six Cheese","description":"Six cheese blend of mozzarella, Parmesan, Romano, Asiago and Fontina","price":"11.99","icon":"/images/4.png"}]

Using an OAuth2 token

Invoking the API using an OAuth2 token is similar to the usual API invocation using the standard API Manager Gateway by generating an access token from the API Store. A sample cURL command is given below.

curl -k -i -H "Authorization: Bearer 20ac019e-16a7-3ba5-8940-7d42c7e56326" https://localhost:9095/pizzashack/1.0.0/menu

You receive a response similar to the following:

HTTP/1.1 200 OK
Date: Sat, 30 Jun 2018 04:17:21 GMT
Content-Type: application/json
Transfer-Encoding: chunked
server: WSO2 Carbon Server

[{"name":"BBQ Chicken Bacon","description":"Grilled white chicken, hickory-smoked bacon and fresh sliced onions in barbeque sauce","price":"13.99","icon":"/images/6.png"},{"name":"Chicken Parmesan","description":"Grilled chicken, fresh tomatoes, feta and mozzarella cheese","price":"9.99","icon":"/images/1.png"},{"name":"Chilly Chicken Cordon Bleu","description":"Spinash Alfredo sauce topped with grilled chicken, ham, onions and mozzarella","price":"17.99","icon":"/images/10.png"},{"name":"Double Bacon 6Cheese","description":"Hickory-smoked bacon, Julienne cut Canadian bacon, Parmesan, mozzarella, Romano, Asiago and and Fontina cheese","price":"16.99","icon":"/images/9.png"},{"name":"Garden Fresh","description":"Slices onions and green peppers, gourmet mushrooms, black olives and ripe Roma tomatoes","price":"9.99","icon":"/images/3.png"},{"name":"Grilled Chicken Club","description":"Grilled white chicken, hickory-smoked bacon and fresh sliced onions topped with Roma tomatoes","price":"13.99","icon":"/images/8.png"},{"name":"Hawaiian BBQ Chicken","description":"Grilled white chicken, hickory-smoked bacon, barbeque sauce topped with sweet pine-apple","price":"27.99","icon":"/images/7.png"},{"name":"Spicy Italian","description":"Pepperoni and a double portion of spicy Italian sausage","price":"13.99","icon":"/images/2.png"},{"name":"Spinach Alfredo","description":"Rich and creamy blend of spinach and garlic Parmesan with Alfredo sauce","price":"27.99","icon":"/images/5.png"},{"name":"Tuscan Six Cheese","description":"Six cheese blend of mozzarella, Parmesan, Romano, Asiago and Fontina","price":"11.99","icon":"/images/4.png"}]


Override endpoint related information

Backend endpoint URLs and credentials for backend endpoints can be provided for each gateway node as system properties. Following are the supported functionalities:

Override endpoint

To override production endpoint for an API (Say TestAPI v1), provide the following system variable at startup,

bash gateway -e TestAPI.v1.prod.endpoint.0="http://wso2.com"

For sandbox endpoint

bash gateway -e TestAPI.v1.sand.endpoint.0="http://wso2.com"

If there is more than one endpoint (for load balance endpoint, etc), use following method to define each endpoint 


bash gateway -e TestAPI.v1.prod.endpoint.0="http://wso2.com" -e TestAPI.v1.prod.endpoint.1="http://support.wso2.com"


To set the endpoint using system properties, use following method (replace . with _ in Linux environment)

export TestAPI_v1_prod_endpoint_0="http://wso2.com"

Define backend basic auth credentials

If the backend EP is protected with basic auth, you have to provide credentials related to that endpoint. Use following system variables to define them

bash gateway -e TestAPI.v1.prod.basic.username="admin" -e TestAPI.v1.basic.password="admin"


If the username is not defined, username defined in the API (During the API implementation time) will be used. 
To set the credentials using system properties, use following method (replace . with _ in Linux environment)

export TestAPI_v1_prod_basic_username="admin"
export TestAPI_v1_prod_basic_password="admin"


  • No labels