Creating "Codeless" Swagger Connectors for Logic Apps

  • [アーティクル]

With the exciting announcement that Azure Logic Apps reached general availability I decided to spend a bit of my weekend re-building a few cloud workflows that help me with my day-to-day. One of my most useful logic apps is one that will monitor our MSDN forum RSS and alert me whenever there is a new post (with similar workflows for StackOverflow and other sources). I could just use one of the many out-of-the-box connectors to trigger via RSS and send me an email or a text message, but I prefer to get these updates through a different service, PushBullet, which I have on all of my devices. I want to send a push notification to all my devices whenever a new post is submitted - and ideally link directly to the post. However, Logic Apps doesn’t (yet at least) have a PushBullet connector, but that was fine. I had a few options to extend Logic Apps:

  1. Create a custom connector like one of the many in our GitHub
  2. Call the API directly via the HTTP action
  3. Author a codeless connector with a Swagger document I can use with the HTTP + Swagger action

For speed and efficiency, I went with option #3. Nothing to code, nothing to manage, and a nice visual designer experience in Logic Apps.

Understand Swagger and the Open API Initiative

Swagger, as the website advertises was created with the following goal:

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Azure Logic Apps can use swagger to discover and cater a design experience across customer and 3rd party APIs.

Now in my case I didn’t see a swagger document in existence for PushBullet - but that’s ok - because authoring a swagger document isn’t too complex.

Authoring Swagger

First off, if you are developing your own API, I would say if at all possible don’t author the swagger by hand. There are dozens of tools for almost every language that will do it for you. I’m partial to Swashbuckle myself. However in this case, I don’t control the code of PushBullet, so I was going to need to author by hand.

Swagger Editor

Swagger gives you a nice Swagger editor you can run and install, but you can even just use their live demo to author basic docs.

Creating PushBullet Swagger

First I found the PushBullet REST API reference so I knew what the API I needed to describe was. I saw a call tohttps://api.pushbullet.com/v2/pushes would allow me to get or send pushes. I quickly fired up Postman and made a call to the API. I knew I had the call I needed, now I just needed to describe it.

Executing with Postman

Swagger only had a few sections I had to fill out in order to mimic this call and create a first class Logic Apps experience:

  • Host: The domain of the service. In this case: api.pushbullet.com
  • basePath: Any prefix needed for calls. In this case: /v2
  • Paths: The paths to make calls. I only needed one path for my use case /pushes Under the /pushes path I needed a description for the POST method.

Those 3 pieces were all I really needed to describe the call. Now luckily Swagger also lets you do a lot of other powerful and useful things like adding descriptions and request and response schemas. I went through and defined all of the request and response schemas for the operation, and exported the JSON.

Saving the Swagger

I prefer to edit my Swagger in YAML, and then when finished I can simply click File -> Download JSON to get it in a format for other services like Logic Apps to use.

Swagger Editor

For a full copy of the swagger document I generated, you can check out my GitHub here

Using in a Logic Apps

Now that the swagger was authored, I needed to access it from my Logic App. Unfortunately you cannot reference a swagger doc hosted in GitHub yet (they don’t like the request headers), but enabling CORS on Azure Blob following these steps here only took a minute and in no time I had a swagger doc in Azure blob I can reference from a Logic App. You are more than welcome to use it as well:

https://jehollanswagger.blob.core.windows.net/swagger/pushbullet.json

This now lets me add a PushBullet action into any of my workflows and have a first class designer experience.

Logic Apps with PushBullet Swagger