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

An OpenAPI catalog for WSO2 APIM and Micro-gateway 320

6 min readNov 29, 2020

[Source: https://45.media.tumblr.com/59ce12f2973199e5042f9d3e07bd2e49/tumblr_o4seodEyWn1s3olk1o1_540.gif]

If you don’t fit into the box, then fix the box to fit yourself in!

In WSO2 API Manager (APIM) and in Microgateway (MGW) the core element that gives business to these products is the API. The APIs are treated as contracts and as a single source of truth (SSOT) in the real business world. The APIs contain all the technical specifications on how data exchange has to be done in day-to-day business. The OpenAPI specification is used to design and generate the REST APIs that contain the API’s metadata, the communication endpoints, how the request and response should be handled, etc.

In order to contain all the details about an API, the OpenAPI is designed to have multiple fields or keys. There are mandatory and optional fields we get in the OpenAPI definitions. This is a global standard that can be optimized by any individual or organization to design and define their APIs. Since this is a widely accepted and global standard, there raises a problem in adapting these fields in a way that they address all the use-cases that can differ from organization to organization.

Spotlight on OpenAPI Vendor extensions

[Source: https://newmanvantage.com/content/images/2019/02/sponge.jpg]

The OpenAPI specification or OAS 3.0[1] provides a way to introduce new fields to the OpenAPI file which are not supported by default, in order to address a various range of use-cases and to apply extra functionalities. These types of custom fields are known as the “OpenAPI extensions”. The OpenAPI extensions are also known as specification extensions or vendor extensions.

Vendor extensions on the action!

[Source: https://i.imgflip.com/1ip4rl.jpg]

In this section of the blog, let’s see how the extensions are defined and used in an OpenAPI definition. Apart from the default fields, if we are to introduce vendor extensions, we have to define them with the following prefix.

x-

For example, if we are to introduce an extension called “proprietor” in the OpenAPI definition, then this extension should be defined as follows.

x-proprietor

Since OpenAPI definitions have become an inevitable part of today’s API business world, many of the leading vendors have utilized the extension feature to expand their OpenAPI specifications’ functionalities. Amazon API Gateway, ReDoc, and APIMatic are some of the leading businesses that have used this feature.

Rules on defining the vendor extensions

[Source: https://s3.amazonaws.com/lowres.cartoonstock.com/politics-pedestrian-crossing-barrier-government-regulation-wmi100305_low.jpg]

When defining the vendor extensions the following criteria must be satisfied.

The vendor extensions

should start with the prefix “x-”
supported on the root level of the API specification. The supported fields are,

1. info
2. paths (individual paths and operations)
3. operation parameters
4. responses
5. tags
6. security schemes

3. can be in one of the following data types

1. Primitive
2. Array
3. Object or null

If the vendor extension is a type of an object or an array of objects, then the object property names do not have to start with the prefix “x-”. In the following example, the x-wso2-production-endpoints is a vendor extension and has properties of an object data type. Therefore, the “urls” and the “type” property names do not have to start as “x-urls” or “x-type”. Instead, they can be defined as “urls” and “type” respectively.

E.g:
x-wso2-production-endpoints: 
    urls: 
      - "https://test.com/bank/accounts"
    type: "https"

WSO2 and OpenAPI vendor extensions

[Source: https://miro.medium.com/max/800/1*6QNc3-7ULpW6hJfIEShh2Q.jpeg]

WSO2 is one of the leading players in the API Management platform and they have APIM and MGW products, in which these OpenAPI definitions are used very heavily. So the WSO2 uses the following extension prefix to define vendor extensions in OpenAPI definitions.

x-wso2

The WSO2 APIM and MGW have their own functionalities which are not covered in the standard OpenAPI specification. Such functionalities are as follows [2].

1. Throttling
2. Endpoints
3. CORS
4. Transports
5. Mutual SSL
6. Cache
7. Security and etc.

In order to address each of these functionalities in the OpenAPI definitions, WSO2 has defined a set of vendor extensions. These vendor extensions can be defined in the OpenAPI manually or via the publisher portal as well. Please note that in this blog post we will be focusing on APIM-3.2.0 and MGW-3.2.0.

OpenAPI storage locations and the differences: WSO2 APIM and MGW

[Source: https://static.wikia.nocookie.net/tomandjerry/images/4/46/JerryJumbo3-1-.jpg/revision/latest?cb=20110131171722]

1. WSO2 APIM

In WSO2 APIM we can create an API using an OpenAPI definition. Even if we create a REST API from scratch, the APIM itself will create an OpenAPI definition with relevant attributes and will be saved in the registry (carbon management-console) in the following location.

/_system/governance/apimgt/applicationdata/provider/<provider>/<API Name>/<version>/swagger.json

After the API has been saved in the registry it will be retrieved to the local entries location with the API ID as the XML file name.

<APIM-HOME>/repository/deployment/server/synapse-configs/default/local-entries/<API-ID.xml>

Let’s compare the API definition in the,

1. Publisher portal (or the API definition that could be retrieved via REST API)
2. Registry
3. Local-entries

The API definition in the registry and in the local-entries will be the same whereas the API definition in the publisher portal or via REST API will be different from them.

API Definition in,
1. Registry = Local-entries
2. Publisher portal = REST API

The main difference is that the WSO2 specific vendor extensions are not available in the OpenAPI definitions located in the registry and in the local-entries. In APIM the registry contains the original API definition. The publisher portal includes more information (WSO2 vendor extensions)at the time it fetches the OpenAPI definition from the registry. But these are not persisted anywhere.

For example, the following WSO2 vendor extensions are not available in the registry or local-entries OpenAPI definitions.

x-wso2-application-security
x-wso2-auth-header
x-wso2-cors
x-wso2-production-endpoints
x-wso2-sandbox-endpoints
x-wso2-basePath
x-wso2-transports
x-wso2-response-cache
x-wso2-owner

The above explanation can be witnessed with the following sample OpenAPI definitions retrieved from publisher portal, registry, and local-entries.

The OpenAPI definition in the publisher portal or retrieved via REST API is as follows.

2. The OpenAPI definition in the registry is as follows.

swagger-carbon-management-console.json

3. The OpenAPI definition stored in the local-entries folder in the name of the API ID.

9b9beae0–9307–40fb-b7be-b0f394fdadd9.xml

2. WSO2 Microgateway

In WSO2 MGW the OpenAPI definition is store in the <MGW Project location>/api_definitions/ location. The MGW project needs to be built as an executable jar that contains all the dependencies and OpenAPI definitions. Therefore, unlike in the APIM, the OpenAPI definition located in the <MGW Project location>/api_definitions/ should contain all the WSO2 vendor extensions. Even though the OpenAPI definition content is slightly different for APIM and MGW, resource-wise both are the same.

Coming up Next…!

In this blog, we were able to get the very essential knowledge of how an OpenAPI is used in WSO2 APIM and MGW along with some internal wirings. In the next blog post, let’s get some hands-on experience in implementing the OpenAPI definitions and get more insights on WSO2 extensions! Hope this was a useful read!

Till then, Stay safe…!

Happy Learning…!!!