This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Microgateway Quick Start
This documentation is for the API Microgateway component that is coupled with WSO2 API Manager 2.6.0.
View the documentation for the latest release - WSO2 API Microgateway 3.0.2.
Before you begin,
- Download the version 2.6.0 of the Microgateway distribution and extract it.
Append the full path of theÂ
/bin
folder of the extracted Microgateway distribution to the PATH environment variable.
If you are unable to append the path, you can alternatively run the Microgateway Toolkit related commands by navigating to the <MGW_TOOLKIT_HOME>/bin
folder and running the commands as ./micro-gw
instead.
Let's go through the main use case of the Microgateway:
Deploy and subscribe to the sample APIÂ
- Open the API Publisher (
https://<hostname>:9443/publisher
)Â and sign in withÂadmin/admin
 credentials. - Close the interactive tutorial that starts automatically if you are a first-time user.
Click the Deploy Sample API button. It deploys a sample API calledÂ
PizzaShackAPI
 into the API Manager.The Deploy Sample API option is available only when there are no APIs in API Publisher. If you have already created a API, this option is not available.
- ClickÂ
PizzaShackAPI
 to open it. - Go to the Lifecycle tab and note that the State isÂ
PUBLISHED
. The API is already published to the API Store. - Sign in to the API Store (
https://<hostname>:9443/store
)Â with theÂadmin/admin
 credentials and click theÂPizzaShackAPI
 API. - Select the default application and an available tier, and click Subscribe.
- When the subscription is successful, click View Subscriptions on the information message that appears.
You have now successfully subscribed to an API. Let's generate a distribution for this API.
Generate a distribution for a single API
It is possible to create a Microgateway distribution for a single API that is in the Published state.Â
For details on how to create a Microgateway distribution for a group of APIs, see Grouping APIs with Labels.
- Navigate to a preferred workspace folder using the command line.
This location is used to run the Microgateway commands and to generate Microgateway artifacts. Set up a project using the command given below,
micro-gw setup <project_name> -a <API_name> -v <version>
When the tool requests for the username and password, use
admin
in both instances. Use the default values for the other parameters by pressing Enter.ÂHere is an example:
$ micro-gw setup pizzashack-project -a PizzaShackAPI -v 1.0.0 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 is successful.
When the above command is issued, the tool connects with API Manager REST APIs and retrieves the API specified above. The source artifacts are generated in the current folder location.
The folder structure looks similar to the following,
. └── pizzashack-project ├── conf │ └── deployment-config.toml ├── src │ ├── extension_filter.bal │ ├── listeners.bal │ ├── PizzaShackAPI_1_0_0.bal │ └── policies │ ├── application_10PerMin.bal │ ├── application_20PerMin.bal │ ├── ... │ ├── subscription_Bronze.bal │ ├── subscription_Gold.bal │ ├── ... │ ├── subscription_Unauthenticated.bal │ └── throttle_policy_initializer.bal └── target
If you re-run the setup command while you already have a project named
pizzashack-project
in the current working directory, you receive an error similar to the following:$ 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, run the setup command with the
-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.
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 Build successful for the project - pizzashack-project
Once the above command is executed, the generated source files are built and a Microgateway distribution is created in theÂ
target
 folder.ÂThe name of the distribution will have the formatÂ
micro-gw-<project_name>.zip
. In the above example, the name will beÂmicro-gw-pizzashack
-project.zip
.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. For example,
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' 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
You have successfully generated and started a Microgateway distribution for the Pizzashack API.Â
Generate a JWT token and invoke 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).Â
Log in to the API Store, click Applications and choose to edit the Default Application. Set the token type to JWT.
Click the Production Keys tab and click Generate Keys to generate an access token to invoke the API.Â
If you have already generated keys before, click Regenerate.
Invoke the API using the JWT token using the following command:Â
Formatcurl -k -i -H "Authorization: Bearer <JWT_token>" <API_url>
For example,
Examplecurl -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: Thu, 26 Jul 2018 16:52:38 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"}]
Alternatively, you can invoke the API 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: Thu, 26 Jul 2018 16:52:38 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"}]