Including Postman Collections In My APIs.json Files

I’m back doing more work on the master stack of microservices that I use to operate API Evangelist. Things were getting critical, as I needed some new features, and since I had put a moratorium on the legacy stack, in order to get the new stuff I wanted, I had to finish the migration for any API I wanted to work on—I’m currently about 70% complete with it all.

One of the features I added to my "API microservice" (yes I went there), which is my microservice for tracking on APIs across the sector, was a set of Swagger import / export endpoints. I wanted a quick way to import Swagger to represent any API, and then easily get an updated version of Swagger out of the system as well, so I added two endpoints:

• Swagger 2.0 Import (POST) - Ability to pass a public URL for a Swagger definition, and it will import into my main database.
• Swagger 2.0 Export (GET) - Ability to request a fresh Swagger specification for any API I am tracking on, and profiled.

I had Swagger import and export features in my old system, but they weren’t clean API endpoints, just custom hacks. Once complete, the next thing on my task list is to generate Postman Collections for the entire stack. I need to be able to monitor my microservices stack with services like API Science and Runscope, and Postman Collections are the common API transaction language, both of these platforms speak. There is one snag, in order to get the Postman Collection, I need my entire stack available in Postman, and I’m sure as hell not manually entering all of them, so I need Swagger 1.2 definitions to be able to be able to automate this. Postman recently said they support Swagger 2.0, but I haven’t been able to get any to work, so Swagger 1.2 it is. So I launched two additional API endpoints:

• Swagger 1.2 Import (POST) - Ability to pass a public URL for a Swagger definition, and it will import into my main database.
• Swagger 1.2 Export (GET) - Ability to request a fresh Swagger specification for any API I am tracking on, and profiled.

Now that I have the ability to export a Swagger 1.2 or 2.0 definition out of my API microservice, I quickly generated Swagger 1.2 definitions for almost half of my services. I was able to easily important these into Postman, and then publish Postman Collections for each set of microservices, and save a copy, which I store in the Github repository for each microservices.

Now that I have a locally available Postman Collection for each API, I added them to the APIs.json, using an x-postman URL type. You can see an icon alongside the Swagger definition, in the APIs.json navigator for each project. Now I have two common formats for describing my APIs, and putting them easily to work via Swagger UI or in a Postman Client. Next step is to import all the generated Postman Collections into API Science and Runscope, to setup up a monitoring layer for the stack. Depending on what public assets are available for me via these services, I will be added more service specific links in APIs.json, like I did for Postman.

My goal is to show the potential for APIs.json as an engine that serves every stop along the API lifecycle.