WSO2 API Cloud - Adding mediation sequences, documents and API thumbnails using CLI Tool.
Tags: wso2, cloud, devops, beginners
Published: 2021-01-24 14:07:41

WSO2 API Cloud delivers an enterprise-ready solution for creating, publishing, and managing all aspects of an API and its lifecycle. To register and get started with WSO2 API Cloud, go to http://wso2.com/cloud/api-cloud/

In my previous article, I was focusing on Designing, Initializing and Deploying APIs to the WSO2 API Cloud **from the command line** using the **APIMCLI tool**. 
<br>

👉 **Previous Article** 

* [WSO2 API Cloud projects initialization and deployment using the CLI Tool](https://dev.to/mihinduranasinghe/wso2-api-cloud-projects-initialization-using-the-cli-tool-9oa)

<hr>

#### In this article, we are focusing on adding mediation sequences, documents and API thumbnails **from the command line** using the **APIMCLI tool**, for APIs in the **WSO2 API Cloud**.

You can follow the same development environment configuration approach which I have explained in my [previous article] (https://dev.to/mihinduranasinghe/wso2-api-cloud-projects-initialization-using-the-cli-tool-9oa).

Once an API project is initialized and replaced the api.yaml file and swagger.json file with our actual files [EX [api.yaml](https://gist.github.com/mihinduranasinghe/6285853c3f186b107e9bddc4d550e16d), [swagger.json](https://gist.github.com/mihinduranasinghe/0b083375f1fea5bcc03f7737804dc933)], I deployed the API using the CLI Tool to the WSO2 API Cloud platform as below : 

The deployment approach was clearly explained in the [previous article](https://dev.to/mihinduranasinghe/wso2-api-cloud-projects-initialization-using-the-cli-tool-9oa)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/kmpjixv2ps30x4mdsx9n.PNG)

## **Adding mediation sequences from CLI.**

An API hosted in WSO2 API Cloud receives requests sent from your consumer applications to your backend, and then sends the responses from the backend to you. The default flow of events of an API hosted in WSO2 API Cloud is depicted in the diagram below.

If you need to modify or transform the requests and responses of your API, you need to engage a message mediation that intercepts the default flow. The API Gateway has a default mediation flow, which you can extend using mediation policies. You can create a custom mediation policy manually, or using a tool, and then engage it with the API. This will enable you to modify the default mediation flow for different use cases according to your requirement.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/i9xo55o1j5nnfmg8e6o7.png)


* [Learn more](https://cloud.docs.wso2.com/en/latest/learn/message-mediation/add-a-sample-mediation-sequence/) about WSO2 API Message Mediation Policies. 

* [Here](https://cloud.docs.wso2.com/en/latest/learn/message-mediation/add-a-custom-sequence-to-your-api/) you can find out how to add mediation sequence policies from the WSO2 API Cloud **Web UI**


#### <u>Let's see how we can do this with CLI</u>

**1.** First of all you need to have prepared your **in-flow**, **out-flow** and 
**fault-flow** Custom **Mediation Policy files (.xml)**

**2.** Here I have attached some sample sequence files for you to get hands-on experience and move forward with this article.  

Download [in-sequence]((https://drive.google.com/file/d/1hL_dcdA7men3XPZfsrerqVyFEnidFLKj/view?usp=sharing)) , [out-sequence](https://drive.google.com/file/d/1tAJCH0b8qmdFW84hNb38TsY4JwKa90Bk/view?usp=sharing), [fault-sequence](https://drive.google.com/file/d/1RJtoRQCKsgDKFtRZSFDFG7nT1GizCjKa/view?usp=sharing)

**3.** You need to create a folder with the name of **"Custom"**, inside every sequence directory in your API project folder structure and you have to keep your respective **.XML** files inside respective **Custom** folders.

As below :

SampleStore
│         ── api_params.yaml
│	  ├── Docs
│	  ├── Image
│	  ├── Meta-information
│---------- 		  ├── api.yaml
│----------   		  └── swagger.yaml
│	  └── Sequences
│----------		 ├── in-sequence
│--------------------			└── Custom
│------------------------------				└── [in-seq.xml](https://drive.google.com/file/d/1hL_dcdA7men3XPZfsrerqVyFEnidFLKj/view?usp=sharing)
│----------		 ├── out-sequence
│--------------------			└── Custom
│------------------------------				└── [out-seq.xml](https://drive.google.com/file/d/1tAJCH0b8qmdFW84hNb38TsY4JwKa90Bk/view?usp=sharing)
│----------	  	 └── fault-sequence
│--------------------			└── Custom
│------------------------------	     			└── [fault-seq.xml](https://drive.google.com/file/d/1RJtoRQCKsgDKFtRZSFDFG7nT1GizCjKa/view?usp=sharing)

**4.** Then you need to enable custom mediation sequences in the API definition **api.yaml** file as well.

Just add these keys to the **api.yaml** :

```sh

# Mediation Sequence
inSequence: in_seq
outSequence: out_seq
faultSequence: fault_seq

```

###### Note that you can add and keep multiple sequence files in the custom folder and you can enable which one to be considered with these keys in api.yaml

**5.** Finally you need to **log into the targeted tenant from the CLI** as I explained in [previous article](https://dev.to/mihinduranasinghe/wso2-api-cloud-projects-initialization-using-the-cli-tool-9oa), and **import the API to the Targeted WSO2 API Cloud Tenant**

```sh
#apimcli login <Environment> -u <Username> -p <Password> 
apimcli login wso2apicloud -u mihindu@wso2.com@development -p PASS54687 -k

```
Also you can login like this :

```sh

#apimcli login <Environment> 
apimcli login wso2apicloud
Username: mihindu@wso2.com@development
Password:

Logged into wso2apicloud environment
```

After logging in to the targeted tenant, you can import the API using the following command.

```sh

apimcli import-api -f ./path/SampleStore -e wso2apicloud --preserve-provider=false --update --verbose -k


```

###### Go back to WSO2 API Cloud Web Platform and you can confirm that your changes have been updated in web UI successfully like this.


![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/3qyhntazamffxo5viyl2.PNG)


## **Adding API Documents from the CLI.**

WSO2 API Cloud enables you to upload documentations to your API projects from the Web UI.

#### Let's see how we can add documents to Cloud API Projects using the CLI tool.

**1.** You need to have prepared the documents that you want to upload to your API Project.

**2.** Keep your documents in the following directory.

**SampleStore > Docs > FileContents > ...**

SampleStore
│         ── api_params.yaml
│	  ├── Docs
│----------  	 ├── FileContents
│--------------------      	 	└── doc1.md
│----------	 └── docs.json
│	  ├── Image
│	  ├── Meta-information
│---------- 		  ├── api.yaml
│----------   		  └── swagger.yaml
│	  └── Sequences
│----------		 ├── in-sequence
│----------		 ├── out-sequence
│----------	  	 └── fault-sequence

**3.** Then you need to create and maintain a **docs.json** file to **configure the documents** with the API Cloud you added to the above directory.

**SampleStore > Docs > docs.json**

Here you can maintain a seperate object for each and every document you added and configure  **id,name,summary,sourceType,visibility,lastUpdate,filePath**

```json

[
  {
    "id": "61d20220-9b81-427f-a189-db933b06a070",
    "type": "HOWTO",
    "name": "ReadMe",
    "summary": "ReadMe",
    "sourceType": "FILE",
    "visibility": "API_LEVEL",
    "lastUpdated": "Jan 13, 2021 9:45:43 PM",
    "filePath": "README.md"
  }
]

```

**5.** Then you need to enable this key like below in **api.yaml** API definition as well.

```yaml

# Enabling Documents Adding
documents: []

```

**5.** Finally again you need to **log into the targeted tenant from the CLI** as I explained above, and **import the API to the Targeted WSO2 API Cloud Tenant**

```sh

apimcli import-api -f ./path/SampleStore -e wso2apicloud --preserve-provider=false --update --verbose -k

```

###### Go back to WSO2 API Cloud Web Platform and you can confirm that your documents have been updated in web UI successfully like this.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/e05maxhmmjdtyn25zc2j.PNG)

## **Adding API Project Thumbnails from the CLI.**

You can upload API Project Thumbnails from the WSO2 API Cloud Web UI as usual.

Here I will show you how you can add a thumbnail using the CLI tool.

**1.** There are few standard wso2 guidelines you need to follow when setting up a thumbnail image. (Download sample [icon.jpeg](https://drive.google.com/file/d/1ARtaBrJUmrclDv4-YTNHMWLtMANZdqTO/view?usp=sharing))

* Thumbnail image must be in the size of **100px X 100px**
* Thumbnail image must be renamed as *"ïcon.jpeg"*

**2.** Then you need to place the image in the following directory.

SampleStore
│	  ├── Image
│----------  	 └── [icon.jpeg](https://drive.google.com/file/d/1ARtaBrJUmrclDv4-YTNHMWLtMANZdqTO/view?usp=sharing)

**3.** Finally again you need to **log into the targeted tenant from the CLI** as I explained above, and **import the API to the Targeted WSO2 API Cloud Tenant**

```sh

apimcli import-api -f ./path/SampleStore -e wso2apicloud --preserve-provider=false --update --verbose -k

```

###### Go back to WSO2 API Cloud Web Platform and you can confirm that your thumbnail changes have been updated in web UI successfully like this.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/ttr8p81w65r0y2ndeoq3.PNG)

<hr>

👉 What's Next?

  * [Testing WSO2 API Cloud APIs using the CLI Tool]()

### **Thank You**

##### ***Hope you all enjoyed and learned something from this. Let me know your comments and suggestions in the discussion section.***

👉 Visit me - [https://mihinduranasinghe.com/](https://mihinduranasinghe.com/)