Role of An OpenAPI Specification

Written by Ali Akthar

Technical Account Manager

The OpenAPI specification (previously recognized as the Swagger Specification) is a powerful definition format to describe RESTful APIs. The specification creates a RESTful interface for quickly developing and consuming an API by efficiently mapping all the resources and operation parameters connected with it. It is easy-to-learn, language-agnostic, and both human and machine-readable. An OpenAPI file lets you describe the entire API, including:

  • Available endpoints and operations on each endpoint (GET, POST)
  • Operation parameters Input and output object generate for each operation
  • Authentication methods

Significance of OpenAPI specification in Integration World

With the developer ecosystem in place, the organizations have started to build their API to expose the same kind of service to more and more fintech players. It is the need of the hour. To make it more agile and convenient, organizations use OpenAPI specification 3.0s.

Now, OpenAPI specification documentation is a technical representation of how a developer wants to consume an API. It includes API-based instructions on how to integrate the API effectively. It also updates the API's lifecycle, such as new versions. Some aspects of API documentation can be generated automatically via Swagger or other documentation. All such middleware technologies use OpenAPI specification documentation like Google Apigee, MuleSoft Any Point Platform, Dell Boomi, IBM API Connect, & Software AG, Web Methods, etc.

OpenAPI specification Support in Google Apigee

In Apigee, OpenAPI specification support is managed by Swagger UI, which dynamically generates documentation for Restful APIs. Swagger primarily classified documentation as a service tool that helps build documentation in JavaScript, HTML, and CSS assets.

One of the main reasons for using OpenAPI specification documentation is to generate a reference that helps build clients libraries in dozens of languages, generate server stubs, use projects to verify your conformance to create samples.

The OpenAPI specification documentation for Restful API comes with information such as the name and description of the API, endpoints, and the mechanism for authentication.

1.	swagger: "2.0"
2.	info:
3.	  title: Sample API
4.	  description: API description in Markdown.
5.	  version: 1.0.0
6.	
7.	host: api.example.com
8.	basePath: /v1
9.	schemes:
10.	  - https
11.	
12.	paths:
13.	  /users:
14.	    get:
15.	      summary: Returns a list of users.
16.	      description: Optional extended description in Markdown.
17.	      produces:
18.	        - application/json
19.	      responses:
20.	        200:
21.	          description: OK

OpenAPI specification Support in MuleSoft, AnyPoint Platform

MuleSoft uses RESTful API Modeling Language (RAML), making it easy to manage the whole API lifecycle from design to sharing. Enterprises not only realize the benefits of RAML's API-spec-centric approach but have used it broadly.

MuleSoft recently joined the OpenAPI specification Initiative of the Linux Foundation, and now MuleSoft's Anypoint Platform explicitly supports OAS (OpenAPI specification, formerly Swagger) for describing APIs. In addition, MuleSoft Design Center supports importing an OAS 2.0 specification in JSON or ZIP format from the file system. It also allows importing an OAS 2.0 specification from the internet.

The API Designer can be accessed in the following ways:

From Anypoint Platform, by downloading API Designer from Github and following instructions to run it locally or embed it in an app; https://github.com/mulesoft/api-designer

API Designer appears and is divided into three panels:

  • Files panel: Shows the default file name api.raml for RAML code. An asterisk precedes the file name to indicate unsaved content.
  • RAML editor panel: Contains generated code: the default RAML version 1.0, the names of the API, and the API version, which you provided to API Manager.
  • API Console: This panel displays your API's data types, resources, and methods for simulating the API. Until you define the API, the Console displays an empty Resources list. Turn on the Mocking Service on the top, right-hand side, and try It.

The files panel lists names of any imported files, such as examples, that you can reference as include files. From the context menu, you can save, rename, and delete a file.

The RAML editor includes the following functions:

  • Checks and highlights syntax.
  • Flags incorrect syntax.
  • Displays a shelf of hints that you can click to insert the next line of code.

In the RAML Editor, you can hover over a red x problem indicator to see a hint about the problem. For example, an indicator says that the api.raml file has not yet been saved:

Designing RAML

The API definition, written in RESTful API Modeling Language (RAML), includes the following things:

  • An optional [baseURI node] at the root of the RAML document
  • API resources, for example the collection of all customers or a specific customer
  • HTTP methods, such as GET, POST, PUT, and DELETE, allowed on each resource
  • The representation of the request and response messages for each method, such as GET /customer/1 → response: application/json

OpenAPI specification Support in IBM API Connect

The OpenAPI specification is widely adopted for REST APIs. IBM API Connect supports the OpenAPI 3.0 specification, with certain restrictions. The existing implementation includes complete support for the Berlin Group NextGen PSD2 requirements.

IBM contains any combination of OpenAPI 2.0 and OpenAPI 3.0 APIs. When publishing a Product that contains an OpenAPI 3.0 API, the API gets validated to guarantee that it is syntactically accurate and that references to configuration resources and policies resolve correctly, in the same way, that OpenAPI 2.0 APIs are validated.

It is also possible to validate OpenAPI 3.0 APIs in any local file system by employing the APIC validate command provided by the developer toolkit CLI.

After retrieving an API object using the developer toolkit CLI or the API Connect REST APIs, there is an oai_version property that explains which OpenAPI specification version API represents. There is no OpenAPI 3.0 API support with the DataPower Gateway; OpenAPI 3.0 API support is provided by the DataPower API Gateway only.

Limitation

The shortcomings to the OpenAPI 3.0 support in IBM API Connect are as follows:

User Interface Limitations

  • The user interface does not currently support some aspects of the OpenAPI 3.0 specification. In such circumstances, use the OpenAPI specification source directly.
  • Almost immediately, the API editor header reflects validation errors identified locally. However, some validation errors can be identified only by the API Manager backend and are not reflected until the API is saved; this means that, on saving an API, some validation errors might appear or disappear.
  • The user interface does not currently support referencing a request body component from the request body of an operation. If you want to reference a request body component, add the reference to the request body of the operation directly in the OpenAPI specification source:
requestBody:
  $ref: '#/components/requestBodies/request_body_component_name'

The reference is confirmed on the details page for the request body in the user interface, however.

  • If, in the API Designer user interface, you create and activate an API of the same name and version as one that has already been activated from the API Manager user interface, the Edit Rate Limit operation fails.

Limitations for APIs that are enforced by the DataPower API Gateway

General Limitation

  • The servers array cannot include more than one server.
  • The url entry in the servers array cannot have variables.
  • Path objects cannot have server object overrides.
  • Wildcarding in response objects is not supported for error codes or success codes.
  • There is no support for converting a WSDL defined SOAP service into an OpenAPI 3.0 API.

Assembly Policies

  • Only the following policies are supported:
  • invoke
  • jwt-generate
  • jwt-validate
  • oauth
  • throw
  • user-security
  • Security
  • The following security schemes are not supported:
  1. HTTP JWT Bearer (HTTP Basic scheme is supported).
  2. OAuth2 with multiple flows (a single flow is supported).
  3. OpenID Connect (OIDC).
  • The use of cookies in an API key is not supported.
  • The validate and map policies are not supported.
  • Schema support is limited to Draft 4 and earlier. Therefore, the following policies are limited to those drafts:
  • gatewayscript
  • set-variable
  • switch
  • json-to-xml
  • xml-to-json
  • parse
  • xslt

IBM Extension to Support OpenAPI specifications

The x-ibm-configuration object properties can be used in the OpenAPI definition file to add extensions that are specific to IBM API Connect.

The x-ibm-configuration extension has the following structure:

x-ibm-configuration:
  enforced: enforced_boolean
  phase: Phase
  testable: test_boolean
  cors:
    enabled: cors_boolean
  activity-log:
      activity_logging_extension
  assembly:
    execute:
      - assembly_component
  gateway: gateway_type
  type: api_type
  properties:
      properties_extension
  catalogs:
      catalogs_extension

The following table lists the various extensions used by API Connect, whether they are required, a description of their use and behavior, and their type.

Extension Required Description Type
Phase Yes Use the phase extension to describe the maturity of the API. It can take the following values:
  • Identified: the API is in the early conceptual phase and is neither fully designed nor implemented.
  • Specified: the API has been fully designed and passed an internal milestone but has not yet been implemented.
  • Ealized: the API is in the implementation phase.
String
Testable Yes Use the testable extension to specify whether the API can be tested using the test tool in the Developer Portal. Boolean
Enforced Yes Use the enforced extension to specify if the API Connect gateway is used to enforce the API.
  • True indicates that the API Connect gateway is used to enforce the API.
  • False indicates that the API Connect gateway is not used to enforce the API.
Boolean
Cors Yes Use the cors extension to specify whether CORS access control is used for the API. The extension has an enabled field which is a Boolean. Object (with a single Boolean field)
Activity-log No Use the activity-log extension to configure your logging preferences for the API activity that is stored in Analytics. The preferences that you specify will override the default settings for collecting and storing details of the API activity. Object
Assembly No Use the assembly extension to describe the application of policies and logic to an API. It contains an execute field that includes an array of policies that are applied in order. It can contain a catch field that consists of an array of error cases to be caught. For information about the use of the execute field, For information about the use of the catch field. Object
Gateway No Use the gateway extension to specify which type of gateway you want to use. If you are using the DataPower® Gateway (v5 compatible) or DataPower API Gateway, it must be included and take one of the following values:
  • Datapower-gateway (DataPower Gateway (v5 compatible))
  • Datapower-api-gateway (DataPower API Gateway)
For information about types of gateways.
String
Type No The type extension takes one of the following values:
  • rest
  • wsdl
Properties No Use the properties extension to define properties for use in an API.
Catalogs No Use the catalogs extension to define Catalog-specific values for properties defined in the properties extension.

The following instance shows the x-ibm-extension section structure of an API that API Connect enforces, is in the realized state, is testable through the test tool in the Developer Portal, has CORS access control enabled, and has a simple assembly that invokes a URL and then redacts a field from the request or response.

x-ibm-configuration:
  enforced: true
  phase: realized
  testable: true
  cors:
    enabled: true
  assembly:
    execute:
      - invoke:
          title: Example Invoke
          target-url: 'https://example.com/api'
          description: Example description
      - redact:
        actions:
          - action: redact
            from: 
              - request
              - response
            path: //*[@name='secondaryAddress']/*[@name='streetAddress']
  properties:
    ID:
      value: 1234
      description: An ID to be used for validating.
      encoded: false
  catalogs:
    Sandbox:
      properties:
        ID: 5678
  • Catch - Use the catch extension to catch errors that occur during an API call.
  • Properties - Use the properties extension to define properties for referencing in an API.
  • Catalog - Use the catalogs extension to assign catalog-specific values to properties defined in the properties section.
  • Activity-Log - If you are using the DataPower API Gateway, you can use the activity-log extension to configure your logging preferences for the API activity that is stored in Analytics. The preferences that you specify will override the default settings for collecting and storing details of the API activity.

Integrating Business Rules

After deploying a ruleset from a decision service, you can call the ruleset a SOAP web service or use the REST API. You can also interact with it by using Open API or API Connect. It requires service credentials for authentication and keeping them separate from the application code.

Challenge faced by the Customer & How Royal Cyber addressed it

Organizations today are looking to connect with the Fintech community and startups. They not only have brilliant ideas but also have a way to revamp the entire business model structure. One of the Retail manufacturers in the US was facing the challenge of connecting with multiple vendors. Therefore, they implemented MuleSoft and used OpenAPI specification capabilities, and they listed some of their APIs on the developer portal for developers to consume. Royal Cyber implemented OpenAPI specification 2.0 and published all the required APIs on the Portal for Fintech, B2B, and startups.

Discover How this Retailer Migrated to ACE 11 and Gained 80% Enhanced Security and Performance. – Click here to read more.

Conclusion

Royal Cyber has extensive knowledge in solving your OpenAPI challenges. With global implementation expertise in the Integration landscape, we have the right set of people and process in place to help your business in this digital transformation journey. For more information, you can email us at info@royalcyber.com or visit www.royalcyber.com.