Introducing the all-new TIBCO Community site!

For current users, please click "Sign In" to reset your password and access the enhanced features. If you're a first-time visitor, we extend a warm welcome—click "Sign Up" to become a part of the TIBCO Community!

If you're seeking alternative community sites, explore ibi, Jaspersoft, and Spotfire.

Jump to content
  • REST Connector Series: Getting to know OAS & Swagger ...


    Manoj Chaurasia

    blog-banner-image-rest-connector-series_part2640x215.fw_.png.f8b55066f9c8475b96676e3176bae3c1.png

    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:

    blog-getting-to-know-swagger-1-768x758.thumb.jpeg.bbac20f0537b2eb83e94acaaf71240e6.jpeg

    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.

    blog-getting-to-know-swagger-image-2-300x197.png.94ebc259ca800f25818b7f6937f78563.png

    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:

    blog-getting-to-know-swagger-image-3.png.82a20de7d96af504f1552fabd07214f3.png

    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:

    getting-to-know-swagger-final.fw_.png.bbb1a104ecad2e8c4c3312cd5212a254.png

    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:

    blog-getting-to-know-swagger-image-5.png.fd64fd86120dcf413f676cbbbfef9fb0.png

    • 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:

    blog-getting-to-know-swagger-image-6.png.39f36c487d8828a7e8ce6153e8ee6d1c.png

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

    Other productivity tools:

    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.


    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...