Ready-made Vs Tailor-made fields in OpenAPI definitions: Part 2
An OpenAPI catalog for WSO2 APIM and Micro-gateway 320
This is the sequel of my previous blog on WSO2 vendor extensions. In the previous blog, we have analyzed the default OpenAPI structure, what are extensions, the need to have extensions, and a glance at how WSO2 utilizes the vendor extensions in OpenAPI definitions. In this blog, we’ll be looking into some in-depth aspects of how WSO2 has used the vendor extensions to get tuned in with the APIM and Microgateway(MGW) features. Let’s begin with analyzing the default OpenAPI fields and the WSO2 vendor extensions.
Supported default fields and WSO2 vendor extensions in OpenAPI Definition
By default, the basic structure defined in OAS 3 for OpenAPI definition is supported by WSO2 APIM and MGW. Some of the supported default fields are as follows.
- OpenAPI version
5. Request body
7. Input and Output models
WSO2 Vendor Extensions
The following are the supported WSO2 vendor extensions in APIM and MGW and the supported level (API or Resource) are listed below.
Enabling WSO2 vendor extensions via Publisher portal
In MGW you can enable all the following extensions manually in the OpenAPI definition. Therefore, the samples denoted on how the extensions will be displayed in an OpenAPI definition is applicable for both APIM and MGW.
In APIM, once you create the API in the publisher portal the OpenAPI definition for the created API can be viewed in Publisher → APIs → Select the created API → API Definitions location. All the above WSO2 vendor extensions can be defined in the OpenAPI definitions manually by editing the OpenAPI definition in the above-defined location. Therefore, let’s take a look at the following methods for adding some of these extensions via the publisher portal to the OpenAPI definitions.
The base path of the API is the combination of the context/API-version defined when creating the API as follows.
This extension defines the endpoint configuration globally which thereafter can be referred to using one of the following extensions.
This is defined during the API creation process as follows.
After the API creation, the endpoint field can be modified in the Publisher → APIs → Select the created API → Endpoints as follows.
3. x-wso2-throttling tier
- API Level
In APIM, the rate-limiting is supported in API and resource or operational levels. The throttling level defines the number of requests the APIM can handle in a given time period(1 min is the default value). By default, when you create an API the operational level throttling will be applied with the “Unlimited” throttling value. The API level throttling is applicable if all the resources are having the same throttling policies.
There are default throttling policies available in APIM and they are defined in the admin portal (https://<hostname>:<port>/admin)as advanced policies.
If the rate-limiting is set at the API level, the x-throttling-tier extension will be defined at the root level in the OpenAPI definition.
- Operational Level
If every resource is having different throttling policies then we can use operational level throttling policies. Similar to the API level throttling you can define Operational level throttling as follows in the publisher portal. So that the defined operational level throttling policy will apply only to that resource.
Please note that the x-wso2-throttling-tier extension is currently supported only in the MGW. In APIM, x-throttling-tier is being used instead of x-wso2-throttling-tier extension.
The same throttling concepts are applicable in both APIM and MGW as well. But in MGW the throttling policies are defined in the <MGW Project>/policies.yaml file and can be referred to in the OpenAPI definition located in <MGW Project>/api_definitions/ folder. Just like we define new throttling policies in the admin portal, in MGW we can define new custom throttling policies in <MGW Project>/policies.yaml as follows.
A custom resource policy has been added to the above policies.yaml file with the policy name 1PerMin.
It can be referred to in the API definition located in <MGW Project>/api_definitions/ folder as follows at the API level/root level.
Similarly, the operational or resource level throttling can be defined as follows in the MGW API definition.
The x-wso2-cors extension specifies the Cross-Origin Resource Sharing (CORS) configuration for the API. This extension should be defined in API Level. This covers a various range of cors properties such as corsConfigurationEnabled, accessControlAllowOrigins, accessControlAllowCredentials, accessControlAllowHeaders and accessControlAllowMethods.
The x-wso2-response-cache is used to configure the response cache in the gateway with a specified duration. This extension is supported only at the API level. By default the response cache is disabled. So, the x-wso2-response-cache will be set as false.
The x-wso2-disable-security allows you to invoke API calls of the resources without being authenticated. This is applicable in both API and resource levels.
Please note that the x-wso2-disable-security extension is currently supported in MGW-3.2.0.
The x-wso2-application-security extension is used to define application security with one of the following security mechanisms. This is applicable at both the API and resource levels.
In APIM, by default, the oauth2 type security schema definition is defined under OpenAPI’s component → securitySchema object as follows without any scope binding.
So in the OpenAPI definition, the “default” security schema will be set for the entire API as follows. Please make sure that you use the same schema name when defining it under securitySchema and in the security tag as well.
To apply or modify the resource level x-wso2-application-security extension, you can follow the below approach.
By default, the following extension will be applied for all the available resources.
If you want to add scopes to these security schemas, you can follow the below approach in APIM. First, you have to create a scope under “Local Scopes”.
Then the scope will be bound to the role as follows in the OpenAPI definition for the existing oauth2 security schema type.
Now, let’s use it as a resource as follows.
It will be displayed in the OpenAPI definition as follows.
The same approach for x-wso2-application-security can be applied to MGW as well. Furthermore, you also can define scopes for security at the API level as follows.
APIM-3.0.0 supports only the scopes defined in default securitySchema and the latest wum version of APIM-3.1.0 and higher APIM version support the scopes in the custom securitySchema.
1. wso2am-3.0.0 scopes with default securitySchema
2. wso2am-3.1.0 scopes with custom securitySchema
The x-wso2-auth-header is used to specify the authorization header for the API in which either bearer or basic token is sent. This is applicable only at the API level. This can be used to define the custom authorization header as follows.
This will be reflected in the root level as follows in the OpenAPI definition.
The x-wso2-transport extension defines the transport protocol on which the API will be exposed. This is a mandatory field set at the API level and you have to define at least one transport protocol. The values could be HTTP or HTTPS or both. This can be defined as follows in the publisher portal.
This will be reflected in the OpenAPI definition as follows.
To secure the APIs with a mutual SSL certificate, you can define the x-wso2-mutual-ssl extension via publisher as follows. You can configure it as a mandatory or optional field. When adding the certificates the mutual SSL currently supports only the certificates with the .crt format. If you have a certificate of some other formats that .crt format, you can use a standard online tool to convert it to the .crt format and upload it.
In APIM and MGW, you can define the backend endpoint URL using the default standard field “servers” and in WSO2 vendor extension x-wso2-production-endpoints or x-wso2-sandbox-endpoints. In APIM even if you define the URL in the servers field it will automatically assign that value to x-wso2-production-endpoints and x-wso2-sandbox-endpoints. But in MGW you can assign backend URL value either with servers field or with x-wso2-production-endpoints or x-wso2-sandbox-endpoints as shown in the following sample OpenAPI definitions.
- servers field
- url: "https://my-json-server.typicode.com/saranki/account-json-backend/accounts"
description: "production endpoint"
In MGW, when you define the servers field you can use the actual backend URL to invoke the API calls. When you use the x-wso2-endpoints, you need to define the x-wso2-basePath as well. The actual backend URL will be masked with the x-wso2-basePath extension. This is because, in OAS 2 the current OAS 3 servers field is represented with host, basepath, and schemes.
servers = schemes + host + basepath
If your backend URL is too lengthy and contains some random strings which cannot be easily read, you can mask by using x-wso2-basePath and x-wso2-endpoints. If you prefer to use your actual backend URL when calling the API resources you can use the standard servers field.
In this sequel blog, we have discussed the practical usage of the wso2 vendor extension and how to implement them in APIM and MGW along with some in-depth details. I hope that this was a useful read and you can refer to this blog when you use OpenAPI definitions in WSO2 APIM or MGW. All your feedback, suggestions, and questions are warmly welcomed…!
See you in another interesting blog…!
Till then, stay safe!