Speed up connectors’ turnaround with swagger specification

What is Swagger

Swagger is the world’s most popular and largest framework of API’s developer tools for the open API specification, enabling development across the entire API lifecycle, from design and documentation to test and deployment.

How Swagger Specifications Have Revolutionized API Ecosystem

In the developer community, with the growing popularity of RESTFUL web services over SOAP there’s a need to have one common standard for designing, developing and documenting APIs. The Swagger specifications come very handy in connecting engineers through their API’s to communicate with each other in a semantic fashion irrespective of the language used to design an API.

Swagger is an framework for describing a common language that everyone can understand. The OpenAPI (Swagger) Specification is a standard, language-agnostic interface to RESTful APIs that allows humans and computers to discover and understand the capabilities of a service without having to access the source code, documentation or through network traffic inspection.

Even though there are few other frameworks like RAML, API Blueprint which have gained some popularity, Swagger is still most popular framework in documenting APIs due to the following factors.

• Open source. Swagger being the first Open Source API framework is great and it’s simple to get started with the OpenAPI Specification. It’s clean, efficient, armed with number of powerful features and helps you to design and document your RESTful interfaces straight out of the box.
• Smart feedback. You can validate your Syntax for Swagger Compliance as you write it with concise error feedback and error handling capabilities. You can also render your API specification visually and interact with your API while you are still defining it.
  
  
• Fully customisable. Easy to configure and customize anything, from line-spacing to themes. You can also generate server stubs and client libraries for your API in any popular language.

The above benefits not only make developer’s life easier but also provide users with smoothly consumable APIs. Any API that adheres to the Swagger Specification are easy to read, iterate and readily consumed. Recently the Swagger Specifications has been moved to Linux Foundation under the name the Open API Initiative, as well as backed by IT giants like Microsoft, Google, Intuiti, Atlassian that focus on creating, evolving and promoting a vendor neutral description format.

In the following section of the article I outline one such use-case in building custom connector, JIRA Service Desk.

Use Case

DBSync uses Swagger Specification through its API connector to build JIRA Service Desk connector that has considerably reduced the whole build cycle in releasing a new connector to the market.

The DBSync’s API connector can effectively integrate with any external system such as JIRA Service Desk by implementing the necessary Swagger Specifications and ApiCode interface. API connector is the fastest way to build any application connector which readily exposes its APIs to the public that may or may not adhere to Swagger or any other API specifications.

Integration is done by documenting all the JIRA Service Desk APIs in JSON object adhering to the Swagger Specifications.

Developing Jira Service Desk connector is as simple as creating a new Swagger JSON object that contains all the endpoints along with the parameters and return types that you would like to expose through the connector (this would fetch all the API metadata that will help in establishing the connection). This JSON object is internally consumed by API connector to expose JIRA Service Desk as an individual connector that can be used in Integration life cycle within the iPaaS.

Leveraging DBSync iPaaS for making API calls with JIRA Service Desk

DBSync’s JIRA Service Desk connector uses JIRA Service Desk APIs along with JIRA Core API’s to move data in and out of the application. This integration consists of REST calls using a JSON request/response made over an HTTPS connection. Therefore all of HTTP methods like, get, post, put and delete are supported as a part of the implementation.

Trigger section is used to fetch data from the source application within the platform. Using JIRA Service Desk connector we expose GET endpoints of the APIs that will equip the user to read data in a controlled way.

Rule section within platform is used to define the manner in a way the user want to write data to the target application which can be either a single data source or multiple data sources. In this section of the platform we expose, post, put API endpoints to pass the data to the desired API. The endpoint names alone are not enough to manage the entire integration life cycle in the iPaaS. Additionally the platform should also know the parameters that need to be passed to an API endpoint and return type parameters that are required for field mappings in transformation process.

Likewise, one can leverage the DBSync iPaaS for connecting with JIRA Service Desk and any other application to facilitate the data flow between them. By including API connector to its catalogue, DBSync has made process of building, publishing and deploying new connectors easier, within just a few days by following Swagger Specification. The platform has the ability to connect with legacy application or SaaS based application that have their API exposed.