This documentation is for WSO2 Microgateway 3.0.1. View documentation for the latest release.
API Microgateway Documentation

All docs This doc
Expand all   Collapse all
||
Skip to end of metadata
Go to start of metadata


Let's host your first API on WSO2 API Microgateway using the WSO2 Microgateway runtime.

Step 1 - Follow the installation prerequisites

Make sure to install and set up all the installation prerequisites.

Step 2 - Generate an executable using WSO2 API Microgateway Toolkit

Step 2.1 - Initialize a project

  1. Navigate to a preferred workspace folder using the command line to set the location that is used to store the Microgateway project.

  2. Create a project named "petstore" by running the following command. This will create the folder structure for the artifacts to be included.

    micro-gw init petstore

    The project is now initialized. A directory with the name "petstore" has been created within the directory where you executed the init command.

    The folder structure is similar to the following.

    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

More Information

Step 2.2 - Build the project

  1. 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.

  2.  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

    More information

    Here are some FAQs on Building a Microgateway project.

Step 3 - Run the API Microgateway

The executable file (.balx ), which includes the API artifacts of the project, is used as input to the WSO2 API Microgateway runtime component for the purpose of exposing the APIs. Follow the steps below to expose the APIs via WSO2 API Microgateway.

  1. Navigate to the  <MGW_HOME>/bin directory.  <MGW_HOME> is the installation directory of the WSO2 API Microgateway runtime

    cd <MGW_HOME>/bin

  2. Execute the following command to start WSO2 API Microgateway.

    Format
    gateway <path-to-MGW-executable-file>
    Example
    gateway /Users/kim/Downloads/TestProj/petstore-project/target/petstore-project.balx

    When WSO2 Microgateway starts successfully, the following log is printed on the console.

    ballerina: HTTP access log enabled
[ballerina/http] started HTTPS/WSS endpoint 0.0.0.0:9096
[ballerina/http] started HTTPS/WSS endpoint 0.0.0.0:9095
[ballerina/http] started HTTP/WS endpoint 0.0.0.0:9090
2019-05-30 18:09:32,540 INFO  [wso2/gateway] - HTTPS listener is active on port 9095 
2019-05-30 18:09:32,541 INFO  [wso2/gateway] - HTTP listener is active on port 9090

Step 4 - Invoke the sample API

Step 4.1 - Obtain 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.

JWT Token
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==

More information

  • You can obtain a JWT token from any third-party secure token service or via the WSO2 API Manager. 
  • Alternatively, you can also use an OAuth2 token to invoke the API.

For more information, see the FAQs on Working with Tokens.

Step 4.2 - Invoke the API

Invoke the API using the JWT token using the following command: Here we will be using an never expiring jwt token acquired from WSO2 API Manager.

  1. Execute the command below to set a self-contained OAuth2.0 access token in the JWT format as a variable on your terminal session.

    TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==

    When you are deploying the Microgateway in production, make sure to change its default certificates.

  2. You can now invoke the API running on the Microgateway using the following cURL command.

    Format
    curl -X GET "<MGW-runtime-hostname>:<MGW-runtime-port>/<API-context>/<API-resource>" -H "accept: application/xml" -H "Authorization:Bearer <JWT_TOKEN>" -k
    Examples
    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

  • No labels
||