Quick Start Guide¶
This is a step-by-step guide on how to quickly deploy an API using WSO2 API Manager (WSO2 API-M) as the Control Plane and invoke it via Choreo Connect.
Before you begin...¶
Install and set up Docker and allocate the following resources for Docker.
- Minimum CPU : 4vCPU
- Minimum Memory : 4GB
Important
Production Deployments - Choreo Connect
The Docker Compose based deployment option explained here is only for tryout purposes. This method is not recommended for production deployments. For production deployments, you can use the following.
- Kubernetes based Choreo Connect deployment with Helm artifacts or YAML artifacts
- Production Deployment Guideline for Choreo Connect
Production Deployments - API Manager
The Docker Compose files referred in this guide are to deploy API Manager with basic configurations. They are the docker-compose scripts provided with the Choreo Connect distribution and are only meant for tryout purposes. In order to deploy WSO2 API Manager in production grade, you can use the following.
- Docker setup artifacts from the API Manager page
- Production Deployment Guideline for API Manager.
Step 1 - Download and extract Choreo Connect distribution .zip file¶
The latest Choreo Connect distribution can be downloaded from https://wso2.com/choreo/choreo-connect/. Extract the Choreo Connect distribution .zip file. The extracted folder will be referred to as CHOREO-CONNECT_HOME
hereafter.
Step 2 - Start Choreo Connect and API Manager¶
Add the host entry to /etc/hosts
file as shown below in order to access the API Manager Publisher and Developer Portal.
127.0.0.1 apim
Start Choreo Connect and API Manager on Docker Compose by executing the Docker Compose script inside the CHOREO-CONNECT_HOME/docker-compose/choreo-connect-with-apim
folder.
docker-compose up -d
Once the containers are up and running, you can monitor the status of the containers using the following command.
docker ps | grep choreo-connect-
Click here if you are using an ARM64 based machine (e.g., Apple M1)
If you are trying this out in an ARM64 based machine (e.g., Apple M1), update the Docker image names with the following:
- docker-compose.yaml files
<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect/docker-compose.yaml
<CHOREO-CONNECT_HOME>/docker-compose/choreo-connect-with-apim/docker-compose.yaml
Existing (Default) image name | Image name for tryout in ARM64 (e.g.: Apple M1) |
---|---|
wso2/choreo-connect-adapter:1.0.0 | wso2/choreo-connect-adapter:1.0.0-ubuntu |
wso2/choreo-connect-enforcer:1.0.0 | wso2/choreo-connect-enforcer:1.0.0-ubuntu |
wso2/choreo-connect-router:1.0.0 | wso2/choreo-connect-router:1.0.0-ubuntu |
wso2/wso2am:4.0.0-alpine | wso2am/wso2am:4.0.0-ubuntu |
Note:
Note that the above Ubuntu based (*-ubuntu
) images are for tryout purpose only, not recommended for a production deployment.
Step 3 - Create and publish an API via API Manager¶
-
Navigate to the Publisher Portal.
-
Sign in with
admin/admin
as the credentials. -
Select REST API from the home screen and then click Start From Scratch.
-
Enter the following API details.
Field Value Name HelloWorld Context /hello Version 1.0.6 Endpoint https://run.mocky.io/v2/5185415ba171ea3a00704eed Note
Let's use a mock service from https://designer.mocky.io/ as the endpoint to test the API. The above endpoint returns the JSON payload
{"hello": "world"}
. -
Click Create & Publish.
This will publish your first API on the Developer Portal as well as deploy it on Choreo Connect. You now have an OAuth 2.0 secured REST API that is ready to be consumed.
Tip
If you are further updating the API, remember to create a new revision using the Deployments tab and deploy the newly created revision to the Gateway, for the changes to be reflected in Choreo Connect.
Step 4 - Invoke the API from Publisher¶
- Open Try Out from the left menu bar.
-
In the Try Out page, you will find an Internal Key that has already been generated for you. You can click the button Generate Key whenever you need a new token.
Tip
When invoking the API, this Internal Key authentication token will be included in the header
Internal-Key
. -
Select one of the listed HTTP methods. Click Try it out and then click Execute to invoke the API.
That's it! You have successfully invoked an API deployed in Choreo Connect.
You can follow the next few steps to get an idea about API Subscriptions, Application Rate limiting and Production Access Tokens.
Step 5 - Subscribe to the API and generate a token¶
-
Navigate to the Developer Portal and select the newly created API.
-
Navigate to the Subscriptions page.
-
Subscribe the API to the default application visible as DefaultApplication with an available Rate Limiting Policy.
-
Navigate to the Applications tab.
-
Click on DefaultApplication, navigate to Production Keys page and click Generate keys to generate a production key.
Tip
To generate keys for the Sandbox endpoint, go to the Sandbox Keys tab. For more information, see Maintaining Separate Production and Sandbox Gateways.
-
Copy the generated access token before proceeding to the next step.
Step 6 - Invoke the API via Choreo Connect¶
Follow the instructions below to invoke the previously created API with the generated token.
-
Click Try Out on the left menu bar.
The resources of the API will be listed.
-
Paste the access token that you previously copied in the Access Token field.
-
If this is the first time you are using the API test console from your browser, open a new tab and navigate to the https://localhost:9095/ URL.
This will prompt your browser to accept the certificate used by Choreo Connect. This is required because, by default, Choreo Connect uses a self-signed certificate that is not trusted by web browsers.
Note
This certificate that is used by Choreo Connect is replaced when deploying the system in production.
-
Click on the
GET
resource of the API to expand the resource and click Try It Out. -
Click Execute.
You should see the
{"hello" : "world"}
response from the API.
Congratulations! You have successfully created your first API, subscribed to it through an OAuth 2.0 application, obtained an access token for testing, and invoked your API with Choreo Connect.