Do you provide Swagger YAML and JSON files with your APIs?

Every developer has their own swagger based on their background, education, coding style, programming language used, etc. In this blog post I am talking about a different kind/type of Swagger.

When developers are interested in using an API provided by a operating system, platform, service, cloud, or device vendor, I’ll bet that one of the first things they will search for is to see if there is an API binding for their favorite programming language. Or, maybe your developer program members are the type of developers who just need the REST/JSON calling information? Where possible, I like to use client and server language bindings, components or frameworks for my development projects. Wouldn’t it be great if all APIs included great documentation and also YAML and/or JSON files for the APIs?

Swagger to the Rescue

With the Swagger YAML and/or JSON files I could use Swagger’s CodeGen tool to create bindings for more than 20 server side languages and more than 40 client side languages. That would be awesome. With Swagger supporting a range of tools, both the API developer creator can build their APIs using their programming language of choice and the API developer consumer can use their favorite programming language.

My one simple statement is “If your API supports REST and JSON then you can Reach out to Every Developer“. The text statement on the Swagger site say it succinctly – “Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.” While most developer program APIs support some common languages including Java, C++, C, C#, JavaScript, PHP, Ruby and Python, there are many other programming languages that also support REST and JSON web services. Why would you intentionally make it harder for developers that use other programming languages?

REST/JSON based APIs work with just about every programming language

My REST/JSON and APIs blog post on the Evans Data DevRelate community site includes links to REST/JSON supporting information for additional programming languages. It’s time for more developer program APIs to make it easier for developers,  using all programming languages, to build applications.

The statement on the Swagger CodeGen tool site says it so well – “Build APIs quicker and improve consumption of your Swagger-defined APIs in every popular language with Swagger Codegen. Swagger Codegen can simplify your build process by generating server stubs and client SDKs from your Swagger specification, so your team can focus on your API’s implementation and adoption.”

Do your Developer Program APIs include Swagger support?

Do you provide you developer program APIs with Swagger YAML and/or JSON files? Send me an email if you do and I’ll be very happy to pass along the word to developers.


David I

David Intersimone “David I”
Vice President of Developer Communities
Evans Data Corporation
Skype: davidi99
Twitter: @davidi99


How do industry associations and standards fit with your Developer Relations program?

No developer program, platform or technology is an island. Developers leverage multiple developer programs, platforms, services, tools, methodologies and industry standards in their every day work. A developer building an enterprise database application will leverage ANSI SQL standard syntax and write code using one or more industry standard programming languages. A developer building a mobile home automation app will access devices via REST/JSON, BluetoothLE, a NEST thermostat, some beacons and a few Z-wave home controllers. In the previous two sentences, I’ve mentioned a developer’s reliance on at least 5 different industry standards that are driven by industry groups, driven by industry alliances in cooperation with global and national standards committees. Things can sometimes get more complicated or cause additional work when there are competing standards. Developer Relations programs and evangelists need to work with their engineering teams to understand the industry standards and work with industry associations to correctly educate developers about their products, platforms, services and devices. We also need to stay on top of the changes that take place in versions of standards.

Industry Associations and Standards

When I assess developer relations programs, one of the aspects I look at is which programming languages your program supports. When I see C++ listed, I look to see if I can find the support for  the approved and draft specifications for ISO C++. When I see that a product or service supports home automation and the Internet of Things, I look for mention of Apple HomeKit, Zigbee, Z-Wave, Bluetooth Classic, BluetoothLE and the soon to arrive Bluetooth 5. When developers start to develop applications that integrate smartphones with cars, developer programs will have to evangelize how their products and services support Apple CarPlay, Android Auto, On-Board Diagnostics II connectors and the Society of Automotive Engineers (SAE).



Developer Relations and Industry Standards

Which developer relations programs are doing a good job of integrating industry associations and standards into the everyday life of their developer members? Here are just a few of the many developer relations programs and developer community sites that work with industry associations and provide information to their members.

MicrosoftWindows Embedded Automotive 7. “Windows Embedded Automotive 7 is an extensible technology platform for automakers and suppliers to deliver in-car experiences that keep drivers connected and informed. Leveraging a range of devices, services and technology, the platform extends work and home into the vehicle through connected car scenarios.”

GoogleAndroid Auto – “For the road ahead, Android Auto was designed with safety in mind. With a simple and intuitive interface, integrated steering wheel controls, and powerful new voice actions, it’s designed to minimize distraction so you can stay focused on the road.”

IntelIntel IoT – “The developer kit is optimized for rapid prototyping—a way to prove or enhance your ideas or turn them into products. The kit provides all the hardware and software you need to speed up prototyping and time to production.”

AutodeskBIM Interoperability – “Autodesk has supported the buildingSMART initiative on COBie (Construction Operations Building Information Exchange) BIM data standard. In January 2013, we completed the independently audited buildingSMART Alliance COBie Design Challenge for Architectural Design and Coordinated Design, achieving 100% positive marks with a complete COBie deliverable that required no additional processing or edits.”

QualcommEmbedded Computing – “Make the next generation of embedded systems more aware, connected, intelligent and interactive with the portfolio of hardware and software solutions on Qualcomm Developer Network. Qualcomm® Snapdragon™ processors for embedded deliver superior performance, low power consumption and support for Wi-Fi, Bluetooth, and GPS connectivity.”

C++ compilersCompiler support for new ISO C++ features. “These include C++11, C++14, C++17 and various technical specifications”.

Philips  – Philips Hue and Apple HomeKit – “The new square-shaped Philips Hue bridge supports the hardware authentication required for Apple HomeKit and enables all your Philips Hue lights to work with Apple HomeKit technology. One of the coolest new features enabled by linking Philips Hue to Apple Homekit is that you can use Siri to control your Philips Hue lights. Turn on your lights. Dim to the desired brightness. Recall pre-set scenes. Even tell Siri to set up for a party.”

AppleBluetooth for Developers – “Create an engaging and connected user experience by integrating Bluetooth® wireless technology in your apps and hardware accessories. And with Core Bluetooth framework, it’s easy for your apps to interact with the growing number of Bluetooth Low Energy (BLE) devices.”

How does your Developer Relations program help members use Industry Standards?

I’ve only mentioned a very few of the tens of thousands of industry standards and associations that help guide application development. Let me know what your developer program does (beyond providing a links) to help your members build awesome apps that rely on multiple industry standards.

David Intersimone “David I”
Vice President of Developer Communities
Evans Data Corporation
Skype: davidi99
Twitter: @davidi99



Which programming language(s) should your developer platform support?

Depending on the products and services your company provides that are supported by your developer relations program, you will find a large number (or a short list) of programming language you should consider. Of course, you can’t always support every programming language that developers might want to use. Each language choose to support will come with costs including: API interfaces and documentation, source code examples, articles and videos to create, developer tools to test with, developer support, training and more. At the same time, supporting more languages can also extend the developer reach for your company resulting in increased revenue and reputation.

So, how do you decide which programming languages to support? You can look inside your own company, review the Evans Data developer surveys, check out programming language popularity sites, see what developer positions are listed on job boards, look at the programming language popularity on Stack Overflow, searching GitHub projects, factor in the leading platforms and technologies, search for what the top computer science and software engineering schools are teaching and read what tech industry luminaries, bloggers and press write about. If that isn’t enough sources for guidance, you can also use dart and Ouija boards, magic 8-ball and D&D dice (just kidding).

Programming Language(s) Popularity

Here are a few places where you can find information about popular programming languages and programming language rankings.

You Can Support any Programming Language if …

A great benefit of using industry standards for APIs, REST/JSON for example, is that just about every programming language in use today can make REST calls and pass parameters and receive results using JSON. If you are using SOAP, CORBA or some other RPC (probably for legacy systems), you should defintely add support for REST and JSON. Some companies are also exploring the use of Apache Thrift and GraphQL for some of their service APIs. If you interested in microservices for your developer platforms, check out this article “Microservice Showdown – REST vs SOAP vs Apache Thrift (And Why It Matters)“. Also check out this recent article about GitHub adding a GraphQL API “Just Because Github Has a GraphQL API Doesn’t Mean You Should Too“.

Let me know what Programming Language(s) your developer program supports

What programming languages do you support for your developer program and platform? Send me an email!

David I.

Twitter: @davidi99