Nov 30, 2020

10 min read

Ready-made Vs Tailor-made fields in OpenAPI definitions: Part 2

An OpenAPI catalog for WSO2 APIM and Micro-gateway 320

[Source: https://media0.giphy.com/media/1zL7bm3xomm5R5PfRH/giphy.gif]

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

[Source:https://media1.tenor.com/images/eaf6129304674c4d262395fa8d6b8096/tenor.gif?itemid=8039421]

Default Fields

By default, the basic structure defined in OAS 3[1] for OpenAPI definition is supported by WSO2 APIM and MGW. Some of the supported default fields are as follows.

1. Metadata
      - OpenAPI version
      - Info
2. Servers
3. Paths
4. Parameters
5. Request body
6. Responses
7. Input and Output models
8. Authentication

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.

[Source: https://mg.docs.wso2.com/en/latest/concepts/openapi-extensions/]

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.

1. x-wso2-basePath

The base path of the API is the combination of the context/API-version defined when creating the API as follows.

Fig 1: Defining the API context and version in the publisher portal

Fig 2: x-wso2-basePath in the OpenAPI definition

2. x-wso2-endpoints

This extension defines the endpoint configuration globally which thereafter can be referred to using one of the following extensions.

x-wso2-production-endpoints
x-wso2-sandbox-endpoints

This is defined during the API creation process as follows.

Fig 3: Defining the API endpoint in the publisher portal

After the API creation, the endpoint field can be modified in the Publisher → APIs → Select the created API → Endpoints as follows.

Fig 4: Modifying the API endpoint in the publisher portal

Fig 5: x-wso2-production-endpoints and x-wso2-sandbox-endpoints in the OpenAPI definition

3. x-wso2-throttling tier

APIM

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.

Fig 6: Default throttling policies defined in the admin portal

Fig 7: Defining and modifying the API level throttling in the publisher portal

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.

Fig 8: x-throttling-tier extension defined in APIM at the OpenAPI root level for API level throttling

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.

Fig 9: Defining and modifying the Operational level throttling in the publisher portal

Fig 10: **x-throttling-tier** extension defined in APIM at the OpenAPI path level for operational level throttling

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.

MGW

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.

policies.yaml

A custom resource policy has been added to the above policies.yaml file with the policy name 1PerMin.

resourcePolicies:
  - 1PerMin:
     count: 4
     unitTime: 1
     timeUnit: min

It can be referred to in the API definition located in <MGW Project>/api_definitions/ folder as follows at the API level/root level.

Fig 11: x-wso2-throttling-tier extension defined in MGW at the OpenAPI root level for API level throttling

Similarly, the operational or resource level throttling can be defined as follows in the MGW API definition.

Fig 12: **x-wso2-throttling-tier** extension defined in MGW at the OpenAPI path level for operational level throttling

4. x-wso2-cors

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.

Fig 13: CORS Configuration in the publisher portal

Fig 14: **x-wso2-cors** extension in the OpenAPI definition

5. x-wso2-response-cache

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.

Fig 15: Response caching configuration in the publisher portal

Fig 16: **x-wso2-response-cache** extension in the OpenAPI definition

6. x-wso2-disable-security

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.

Fig 17: Disable operation level security in the publisher portal.

Fig 18: **x-wso2-disable-security** extension defined at the resource level in the OpenAPI definition

Fig 19: x-wso2-disable-security extension defined at the API level in the OpenAPI definition

7. x-wso2-application-security

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.

1. basic_auth
2. api_key
3. oauth2

In APIM, by default, the oauth2 type security schema definition is defined under OpenAPI’s component → securitySchema object as follows without any scope binding.

Fig 20: Define the security schema in the OpenAPI definition

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.

Fig 21: Using the security schema in the OpenAPI definition

To apply or modify the resource level x-wso2-application-security extension, you can follow the below approach.

Fig 22: Configure the application-level security

By default, the following extension will be applied for all the available resources.

Fig 23: The x-wso2-application-security in the OpenAPI definition

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

Fig 24: Defining the local scopes in the publisher portal

Then the scope will be bound to the role as follows in the OpenAPI definition for the existing oauth2 security schema type.

Fig 25: The defined scopes will be displayed as above in the OpenAPI definition

Now, let’s use it as a resource as follows.

It will be displayed in the OpenAPI definition as follows.

Fig 27: Resource level security with scopes in the OpenAPI definition

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.

Fig 28: Define the security schema with scopes in the OpenAPI definition

Fig 29: Usage of the security schema with scopes in the OpenAPI definition

Tip:
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

Fig 30: Define the default security schema with scopes in the APIM-3.0.0 OpenAPI definition

Fig 31: Usage of the default security schema with scopes in the APIM-3.0.0 OpenAPI definition

2. wso2am-3.1.0 scopes with custom securitySchema

Fig 32: Define the default security schema with scopes in the APIM-3.1.0 OpenAPI definition

Fig 33: Usage of the default security schema with scopes in the APIM-3.1.0 OpenAPI definition

8. x-wso2-auth-header

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.

Fig 34: Configuring the auth header in the publisher

This will be reflected in the root level as follows in the OpenAPI definition.

Fig 35: The x-wso2-auth-header in the OpenAPI definition

9. x-wso2-transport

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.

Fig 36: Configuring the transport-level security in the publisher portal

This will be reflected in the OpenAPI definition as follows.

Fig 37: The x-wso2-transports in the OpenAPI definition

10. x-wso2-mutual-ssl

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.

Fig 38: Configuring mutual SSL in the publisher portal

Fig 39: The x-wso2-mutual-ssl in the OpenAPI definition

Bonus Bonanza!

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

servers:
    - url: "https://my-json-server.typicode.com/saranki/account-json-backend/accounts"
      description: "production endpoint"

servers.yaml

2. x-wso2-endpoints

x-wso2-production-endpoints: 
    urls: 
      - "https://my-json-server.typicode.com/saranki/account-json-backend/accounts"

wso2-extensions.yaml

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.

Wrap Up…!

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!

Happy Learning!!!