In an effort to help folks understand the many layers of just exactly what is an API and how people are using them, I'm going to emphasize (again) the importance of sharing your API definition publicly. I'm not going to talk about why you should have an API definition for your API, if you need a reason, go look at the growing number of ways that API definitions are driving a modern API life cycle--this post is about making sure you are sharing it properly once you have one crafted.
I'm increasingly stumbling across OpenAPI Spec-driven Swagger UI documentation for APIs which I then have to fire up my Chrome developer tools to reverse engineer the path of the OpenAPI Spec--this is dumb. If you have an API definition available for your API, make sure it is available in a prominent location within your API portal, preferably using an easy-to-find icon and supporting link.
Your API definition isn't just driving your API documentation. They are being used for API discovery search engines like APIs.io, to get up and running in API clients like Postman, and to help me monitor, test, and troubleshoot my API integrations using Runscope. Please stop hiding them! I know many of you think this is some secret sauce, but it isn't. You should be proudly sharing your definitions, and making them available to your consumers with one click, so they can more quickly integrate, as well as successfully manage their ongoing integration.
