Let's get started. See the video tutorial here or a separate step-by-step tutorial below.
Let's host your first API on WSO2 API Microgateway using Docker.
Step 1 - Follow the installation prerequisites
Make sure to install and set up Docker and the installation prerequisites for the Microgateway Toolkit.
Step 2 - Generate an executable using WSO2 API Microgateway Toolkit
Step 2.1 - Initialize a project
Create a project named "petstore" by running the following command. This will create the folder structure for the artifacts to be included. The project is now initialized. A directory with the name "petstore" has been created within the directory where you executed the The folder structure is similar to the following.micro-gw init petstore
init
command.petstore
├── api_definitions
├── conf
│ └── deployment-config.toml
├── extensions
│ ├── extension_filter.bal
│ ├── startup_extension.bal
│ └── token_revocation_extension.bal
├── interceptors
├── policies.yaml
├── services
│ ├── authorize_endpoint.bal
│ ├── revoke_endpoint.bal
│ ├── token_endpoint.bal
│ └── user_info_endpoint.bal
└── target
└── gen
Step 2.2 - Build the project
Add the API to the project.
Navigate to the/petstore/api_definitions
directory. Add the API definition(s) to this
directory. Let's use the Petstore sample open API definition.If you open the Open API Specification (OAS) document of the Petstore API using a text editor, you will notice the resource (path) definitions of the API following the standard Open API Specification. You will also see the target server (back-end) URL of the API under the "x-wso2-production-endpoints" OAS vendor extension. WSO2 Microgateway uses this interface definition and the target server URL to generate a gateway proxy for the Petstore API.
Use your command line tool to navigate to where the project directory ("petstore") was created and execute the following command to build the project
An executable file (/petstore/target/petstore.balx
) is created to expose the API via WSO2 API Microgateway.micro-gw build petstore
Step 3 - Expose the sample API via WSO2 API Microgateway Docker image
Run the executable file, which you created in step 2.2 (2.) , using the WSO2 API Microgateway Docker image. The following command exposes the API https endpoint on port 9095 and the context of the API is "/petstore/v1".
docker run -d -v <project_target_path>:/home/exec/ -p <host-HTTPS-port>:<container-HTTPS-port> -p <host-HTTP-port>:<container-HTTP-port> -e project="<MGW-project-name>" <MGW-Docker-image-name>
<project_target_path> -
The path of the target directory created inside the project directory.
docker run -d -v /wso2am-micro-gw-toolkit-3.0.1/bin/petstore/target:/home/exec/ -p 9095:9095 -p 9090:9090 -e project="petstore" wso2/wso2micro-gw:latest
Step 4 - Invoke the sample API
Step 4.1 - Obtain a token
After the APIs are exposed via WSO2 API Microgateway, you can invoke an API with a valid JWT token or an opaque access token. In order to use JWT tokens, WSO2 API Microgateway should be presented with a JWT signed by a trusted OAuth2 service.
Let's use the following sample JWT token for the quick start guide.eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
Step 4.2 - Invoke the API
Invoke the API using the JWT token using the following command: Here we will be using a never expiring JWT token acquired from WSO2 API Manager. Execute the command below to set a self-contained OAuth2.0 access token in the JWT format as a variable on your terminal session. When you are deploying the Microgateway in production, make sure to change its default certificates. You can now invoke the API running on the Microgateway using cURL as belowTOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
curl -X GET "<Docker-hostname>:<Docker-port>/<API-context>/<API-resource>" -H "accept: application/xml" -H "Authorization:Bearer <JWT_TOKEN>" -k
curl -X GET "https://localhost:9095/petstore/v1/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k
curl -X GET "https://localhost:9095/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k