Written by Ali Akthar
Technical Account ManagerThe 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:
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.
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
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.
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:
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:
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:
The API definition, written in RESTful API Modeling Language (RAML), includes the following things:
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.
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.
Limitations for APIs that are enforced by the DataPower API Gateway
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:
|
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.
| 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:
|
String |
Type | No | The type extension takes one of the following values:
|
|
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
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.
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.
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.