REST Connector Series: Getting to know OAS & Swagger ...

In the last post, we introduced you to the REST Connector for the Connect capability of TIBCO Cloud Integration and how you can generate connectivity using an OpenAPI Specification. In this post, we?ll get to know the specification a little better, and introduce some great Swagger productivity tools.

Why get to know OAS?

Maybe you already have a specification, but want to modify it! Not all the specs I?ve seen actually validated successfully ? so we needed to modify them before using them. Or, maybe you don?t have a specification and want to build one to support custom REST calls. Both are great use cases, and much easier than you may think!

How we approach OAS

1. Swagger Tools

Swagger offers a number of great products, and they?re all basically free to use. The Swagger UI is an intuitive way to visualize and test API methods (live demo here). But, the Swagger Editor includes the specification text and the UI all in one!

Swagger Editor is where I spend most of my time: http://editor.swagger.io/#

1. JSON or YAML:

OpenAPI Specs can be documented in JSON or YAML. At the time of writing this, the REST Connector for TIBCO Cloud Integration only reads from JSON ? but it?s very easy to convert between the two, especially in the Swagger Editor.

When I?m editing a spec, I use YAML. There?s less to write, and you?re not opening and closing quotes or curly braces:

This API spec for Uber only has 5 methods but is described in a total of 374 JSON lines vs. 266 YAML lines ? and not to mention, the Swagger Editor has better intelli-sense and styling for YAML.

I spend most of my time working in YAML and then saving as JSON.

1. Defining what you need

OAS covers almost everything in a RESTful API. And there is a method to the madness; I found a nice site to help you ?map? from Handyman out where to define the properties of your API calls:

Screenshot of the Open API from API Handyman

Check out this interactive mapper, here: http://openapi-map.apihandyman.io/?version=2.0

Minimal specs are going to look like the following:

CORS

Cross-Origin Resource Sharing (CORS) is a technique to prevent websites from doing bad things with your personal data, and most browsers are going to enforce it. You don?t need to be expert on CORS to use Scribe?s REST Connector, but occasionally, you might need to enable CORS on your browser to use the Swagger Editor?s ?Try it Out? feature.

I spend a lot of time testing API calls in the Swagger Editor, and I need to have CORS setup to do that.

Common Errors from Swagger Editor that are probably caused by CORS:

• Code: Undocumented
• Details: TypeError: Failed to fetch
• Details: TypeError: Cannot read property ?xyz? of undefined

Setting up CORS:

You can just add these extensions to your browser:

• Google Chrome: https://chrome.google.com/webstore/detail/allow-control-allow-origi/nlfbmbojpeacfghkpbjhddihlkkiljbi?hl=en
• Mozilla Firefox: https://addons.mozilla.org/en-US/firefox/addon/cors-everywhere/

Just make sure you turn off the CORS plug-in when you?re not in the Swagger Editor

Other productivity tools:

• Start saving and sharing your Specs with SwaggerHub: https://app.swaggerhub.com/search
• Convert those Postman Collections to Swagger 2.0 with APIMATIC: https://apimatic.io/transformer
• Convert API JSON Body/Responses using the Swagger Toolbox: https://swagger-toolbox.firebaseapp.com/#
• OpenAPI map: http://openapi-map.apihandyman.io/?version=2.0
• Sample OpenAPI specs: https://apis.guru/browse-apis/

What?s Next?

Now that you have an overview of the Spec and the Tools, go learn by doing! Build a spec and test it out in the Swagger Editor. In my next post, we?ll connect to your spec in TIBCO Cloud Integration.

Upcoming posts:

• Connecting with Scribe REST Connector
• Common integration patterns with REST
• Helper-Tools

First Published May 18, 2018

About the Author

Nate Keefe is a Product Manager at TIBCO Software.