If you are in an industry being impacted by technology, you have probably become very aware of the term Application Programming Interfaces, more widely known as APIs, and how they are driving web applications, mobile applications, and increasingly everyday objects in our homes, cars, businesses, and across the public landscape. If you are finding yourself part of this growing conversations, you have most likely have also heard talk of a new breed of API definition formats that are becoming ubiquitous like Swagger and API Blueprint.
API definitions are a way to describe what an API does, providing a machine readable blueprint of how to put the digital resource to work. API definitions are not new, but this latest round of available formats are taking the API conversation out of just IT and developer groups, and enabling business units, and other key stakeholders to participate throughout the API life-cycle. Much like the latest wave of web APIs has made data, content, and other digital resources like video and images more accessible, API definitions are making APIs more accessible across the rapidly expanding digital business landscape.
The first widely available API definition format was the Web Services Description Language (WSDL), which is an XML format established in 2001 that described web services. Much like web services (an API predecessor), WSDL was a very technical vision of APIs, something dictated by IT, and developer groups, with heavy top down governance from business and industry leadership. While web services, and WSDL are still ubiquitous across the enterprise, they are rapidly being replaced with much lighter weight, simpler web APIs that use the Internet as a way of delivering the digital data, content, and resources web, mobile, and devices are demanding in 2015.
Along the way, newer, more web friendly API definition formats emerged, such as Web Application Description Language (WADL), but ultimately WADL was something that never took root, suffering from many of the same illness of its predecessor WSDL. It wasn't until a new format called Swagger was born, that we started to see the conversation around how we define, communicate and develop standardized tooling around APIs evolve, providing an open specification for defining all the details that go into an API.
Swagger provided developers a way to describe an API that was more in sync with everything else modern API developers were used to, including using JSON, rather than the XML of previous web services, WSDL and WADL. Swagger gave us something more than just way to define APIs, it gave us swagger UI, which is a interactive version of API documentation that made learning about what an API does, and how to integrate with it, a hands on, interactive experience. This new approach to documentation gave us a solution to the number one problem plaguing API providers, which was out of date documentation that confused consumers.
Shortly after Swagger began seeing wide adoption because of the interactive documentation it provided for APIs, a new API definition format also emerged called API Blueprint, which provided interactive documentation, but rather than using JSON, it used Markdown, making the process of defining APIs a little less intimidating for non-developers. Apiary, the makers of API Blueprint did another thing that would move the conversation forward again, making the reasons for defining APIs in these formats, more about API design, than just about delivering up-to-date documentation.
Using API Blueprint, API designers could define an API, before any code was actually written. Developers could craft an API using Apiary's tooling, then a mock version of an API could be generated, which could be shared with other project stakeholders, from business users, to potential web or mobile developers. This process saves considerable time, money, and other resources in ensuring than API would be something web, mobile, and device developers could actually put to use. With two new API definition formats Swagger, and now API Blueprint, the processing of defining, designing APIs in a machine readable way, was accessible to everyone, across a rapidly expanding API life-cycle.
This evolution has all occurred over the last 4 years, a period which has also produced other API definition formats like RSDL, RADL, RAML, I/O Docs, and MSON--just to name a few. All of these API definition formats are quickly becoming the preferred format for not just defining, and designing APIs, as well as delivering documentation. Another positive by-product has been that a new breed of API service providers are also using it as the central definition for quickly putting their services to work on any API, for documentation, mocking and virtualizing APIs, generating server code, producing software development kits (SDK), and setting up essential testing and monitoring to keep APIs stable and reliable for consumers--the API definition driven life-cycle continues to expand.
In 15 years, like APIs, the API definition formats have moved out of the real of the technical, and are providing vital business interactions that ensure APIs meet critical internal, partner, and public needs. They are also being applied to bring much needed balance to the political side of API operations, from making sure APIs are stable, and available, to defining pricing, rate limits, terms of service, and even helping secure APIs that operate on the open Internet.
API definitions have become a machine readable contract that defines the boundaries of a relationship between API provider, and its consumers. Acting as a central truth, that is crafted by developers and API architects to govern how an API operates, from mocking to client integration, but in a way that is also setting the technical, business, and legal expectations of consumers. This API definition-driven contact is transcending the often proprietary, black box algorithms that make an API function behind the scenes, providing a portable, shareable, machine readable contract that can be shared internally, and externally with partners or the general public.
The importance of this new layer, and its role in the future of software development can be seen playing out in the Oracle v Google API copyright case, where Oracle (using the courts) has set the precedent that the naming, and ordering of your interface is separate from the code, and falls under copyright protection. Beyond the core legal case, the questions, and understanding of exactly what is code has been even more interesting. Many API architects do not see APIs as anything but code, having not seen impacts of the modern API definition movement within their architecture yet.
API definitions aren't just about defining the URLs, parameters, headers, and other aspects of API operations that developers need to know, it is also bringing much needed clarity and awareness of value generated by APIs among business users, and the end-users of the applications that APIs are powering. API definitions provide a common format in markdown, YAML, or JSON, that describe the technical surface of an API, but then also take this technical specification, and allow it to be applied across every stop along the API life-cycle, from idea to deployment, to resulting integration with web, mobile, and device applications.
As APIs make their way into almost every aspect of our business and personal lives, driving our social relationships with family and friends, meter our connections to our utility companies, connect us to educational and healthcare opportunities, this touch-point between platform, and the web, mobile, and device applications it powers, is becoming increasingly critical. To businesses this layer represents critical supply chains, but to each individual this touch point is where all of our life bits flow--further emphasizing the importance of, but also the sensitivity required in defining APIs in a meaningful way, that makes sense to EVERYONE involved.
In 2001, a WSDL definition was very much about communicating what a service did between platform and an the system that was integrated, something that only involved IT, and developers. In 2015, a modern API definition format provides the same benefits that WSDL has historically delivered, but it is also addressing the business, and political elements of how Internet enabled software works. A modern API definition provides:
- a medium for API designs, architects, and business stakeholders to craft exactly the API that is needed, before any production code is written.
- a necessary set of instructions needed for a quality assurance (QA) team to make sure an API meets business requirements
- a definition of sandbox, mocking, simulation, and virtualization environments that developers may need to be successful
- what a developer needs to integrate with another system, or build an application through interactive documentation, and even complete Software Development Kits (SDK)
- what the API testing, monitoring, and performance groups will need to ensure service level agreements are met or exceeded
- the known surface area that security auditor will need to properly secure the infrastructure web, mobile, devices, and ultimately users will depend on
- a map that government regulators can use to understand the industry landscape, and help keep all players in alignment with the nations priorities
This is just a sampling of how API definitions are being used as a driver for what is widely being called the API economy, which is the heart of cloud, mobile, big data, Internet of Things (IoT), and almost every other technical trend of the last ten years. While API definitions provide the much needed machine readable instructions for computers to understand what occurs at these vital API touch-points, they also provide the much needed human readable instructions, that people can use to interpret business agreements, individual relationships, that are playing out across our increasingly digital lives.
