Recognizing APIs as a driver of business and strategic initiatives is a fairly recent development, and organizations have now started to invest heavily in their API strategy.
Organizations that are making significant investments in developing API strategies go beyond traditional technology leaders. Industries — from financial services to healthcare, education to manufacturing, and many more — have seen a significant growth in API adoption.
This has been accompanied by an explosion in adoption in API description formats, like the OpenAPI Specification (formerly known as the Swagger Specification), which provide a contract for your API that is language agnostic and human readable, allowing both machines and humans to parse and understand what the API is supposed to do.
Today, thousands of organizations — both large and small — use the OpenAPI Specification (OAS) to streamline the development and drive adoption for their APIs. Implementing OAS across your organization’s internal and external APIs comes with a unique set of challenges, especially when attempting to scale multiple API projects across a number of different teams.
This is where having a workflow to facilitate the implementation of OAS can come in handy.
The goal of this eBook is to introduce an easy-to-follow workflow for working with OAS within your organization.
Transforming to an API Platform
Application Programming Interfaces, or APIs, have been around long before the invention of the PC and were always viewed as technical assets. However, in the past decade, the disruption in information — caused by the Internet, social media, e-commerce, and mobile devices — has led more organizations to understand the importance of APIs as channels of distribution for data and services.
Today, it is estimated that the number of public APIs is around 50,000. This does not include the thousands of privately managed internal APIs, which continue to gain adoption across major industries around the globe. According to SmartBear’s 2016 State of API Report, 1 in 5 API providers only began developing APIs within the last five years alone.
API adoption is only set to increase with the exponential rise in the number of connected devices. The IoT revolution is also upon us, with home devices, bots, and wearable devices all contributing to our growing desire to stay connected. By 2020, it is estimated that every person in the world will have seven devices, on average.
This is further proof that organizations should start thinking about their API strategy, as APIs are the best way to penetrate across all of these different platforms and devices.
An Introduction to OAS-Driven Development
APIs have clearly moved in the direction of fueling business growth. Companies that want to leverage APIs need to account for good, self service consumption with minimal effort by 3rd party developers. In the past, APIs were not meant to be used by a lot of people. APIs were data driven, and were meant to solve a few special use cases of connection and communication. Documentation was minimal, if any, and the canonicals used followed jargon directly from the core database, meaning no one outside a small network of people could understand them.
Needless to say, APIs of the past weren’t meant for self-service consumption. The above no longer applies to the modern web API. The new age of REST APIs, unlike their predecessors, are not data driven, but more consumer driven. Well-designed APIs that solve a real consumer problem is the name of the game, and we’re seeing this focus in APIs from companies like Dropbox, Stripe, and eBay. Reusable interfaces based on HTTP standards are now required by a lot of companies that allow for reuse of data and functions, built for consumer demand and self-service.
Enter the OpenAPI Specification (OAS)
The OpenAPI Specification (OAS) is to REST what WSDL was to SOAP. It provides a common framework for designers, developers, testers, and devops to build and maintain APIs. Think of the specification as a set of rules to build and implement a REST API.
The OAS is language agnostic, and is both human and machine readable, which allows both people and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. Take for example the ability to automatically generate interactive, beautiful API documentation straight from an OAS definition.
The interactive documentation has evolved into its own specific tooling called Swagger UI. The Swagger UI allows both development teams and end consumers to visualize and interact with the API’s resources, without having to manually integrate and implement the API into their own applications.
Benefits of adding OAS to your API:
- The proper canvas for API design and collaboration: OAS provides a single point of focus for your team to collaborate on the design of the API before you begin coding.
- A clear and formal mechanism for reuse with integrity: There are mechanisms inside the OAS definition that are clearly set for reuse and reference across common objects. They don’t require the person who wrote the definition to explain what it means.
- The proper tooling for automation: OAS provides theright structure and tooling for server template generation — either traditional or serverless. A part from server templates, it also supports the generation of client SDKs in almost every popular client language.
- The necessary information for testing automation and monitoring enhancement: Your QA team can import the OAS definition into their testing solutions, reducing the guess work that can be involved in understanding the APIs operations.
The Role of OAS in the API Lifecycle
In order to succeed in today’s competitive, interconnected business landscape, organizations must give their API programs a first-class treatment that gives developers the flexibility to integrate with their ever evolving internal and external environments, in the workflow of their choice.
This is a big reason why choosing the right tool for the API lifecycle management becomes important. For most teams, the API lifecycle with OAS will look something like this:
Benefits of an OAS-Driven Approach
OAS-driven API development advocates for designing the API’s definition first before any other lifecycle operation has been implemented. This means even before you start building the API’s business logic, before you test the API for any errors or defects, or any other lifecycle function, you will design the API’s interface, detailing the exact requests and responses your API end points will showcase.
The OAS-driven approach brings with it some great benefits that directly relate to a consumer-centric approach to API development.
- Better Developer Experience (DX): Good developer experience for API consumption is critical in a hypercompetitive API ecosystem. You can actually focus on the API consumer’s needs beforehand. This allows you to have a developer-centric approach and ensure catering to if your end consumers in an optimal fashion before racing time and other aspects of the development.
- Enables Independence: The approach reduced dependencies between different teams working on your API, like the front-end and back-end teams, or the architects, tech writers and QA. This is because the definition of the API keeps various stakeholders aligned on what the API is supposed to do, and how it relates to their job function. It acts as the contract between the API’s intended service and its functionality, and ensures easier communication between them.
- Faster go to market: Since dependencies are removed, different teams can actually perform their functions at a much faster and efficient rate. The hand-off process between teams is significantly easier, which makes for your APIs being released at a much faster rate.
- Help external folks understand the API: Designing the API first acts as a forcing function to build a consumer friendly API that is easy to understand and use. This also allows your technical writing team to create amazing documentation from a well designed API.
- Create tests for your API: Your OAS definition provides a contract that describes what responses look like when someone calls your API. This contract can be re-purposed to create test cases. That can drastically decrease the amount of setup team needed to test your APIs. You can create functional tests, load tests, by importing your API definition.
- Generate implementation code and SDKs: In addition to generating documentation, OpenAPI definitions can be used to accelerate development by creating implementation code and SDKs. API definition files can be imported into a number of different tools like Swagger Codegen and SwaggerHub. These tools create code in many different languages, like Java, Scala, and Ruby.
- Make your API live: API gateways like Amazon API Gateway, Azure, Apigee, or Google Cloud, all take API definitions to create a live API.
- Monitor your API: Ideally, you want to know if your API has issues before your customers notice. If you import your definition into a tool like Alertsite, the API can be monitored automatically.
For many organizations making the complete transition to an OpenAPI-driven approach — also commonly known as the “design first approach” — won’t always be possible overnight. In some cases, teams still follow a code first approach, in which the OAS definition is generated for an existing API that is already built and may already be in deployment. The code first approach is a more traditional form of building APIs with development of code happening after the business requirements are laid out, eventually generating the documentation from code.
Developers can start implementing the API much faster if they start coding the API directly from the requirements document. This is important if your go-to market strategy emphasizes speed and agility as important factors for the success of the API program. The fact that automation is much easier in the code-first approach helps strengthen this case, with a lot of libraries supporting scaffolding server code, functional testing, and deployment automation. There are open source tools that can be leveraged to generate OAS definitions from existing APIs, either during runtime or build time by adding annotations to your API code.
You can also leverage a tool like Swagger Inspector, which lets you quickly execute any API request, validate its responses and generate a corresponding OpenAPI definition. Use Swagger Inspector to quickly generate your OAS-based documentation for existing REST APIs by calling each end point and using the associated response to generate OAS-compliant documentation, or string together a series of calls to generate a full OAS document for multiple API endpoints.
API Development with OAS at Scale
While more and more organizations are embracing design as a critical step in the software development lifecycle, and the lifecycle of their APIs, very few organizations have figured out how to effectively design APIs at scale.
When you’re working within a single team on a confined number of services, design is easier to manage and relying on PDF style guides or wiki pages may be enough to keep everyone aligned. But what happens when that design process needs to scale across multiple teams and hundreds or even thousands of different APIs?
Optimize Your API Workflow with SwaggerHub
One of the biggest challenges teams face when implementing an API strategy is ensuring that different team members, with varying skillsets and responsibilities, get involved at the right stage of the API lifecycle.
Other challenges include:
- Team management and collaboration: How do you work across teams to update OAS definitions, and write detailed documentation for your API?
- Version management: As organizations continue to iterate on the design and documentation of an API, the complexity of managing multiple versions of their APIs is introduced. How does an organization effectively manage multiple versions of the same API?
- Secure hosting and sharing of OAS definitions: Maintaining a central repository for teams to access OAS definitions becoming increasingly important as you scale your API strategy with OAS. How do teams think through securely orchestrating various aspects of their API lifecycle?
- Sync with existing toolset: How do you keep your internal and external environments updated with the different versions of the API, especially when having your software and API development taking place across various external systems like Source Control Hosts, API Management platforms and testing suites?
Addressing these challenges requires organizations to adopt an optimal API development workflow, and identify the necessary tools to optimize that workflow across all stages of the API lifecycle — from design and document to test and deployment.
We launched SwaggerHub to change the way teams work together to design and document their APIs. Over the last year, we’ve spoken to hundreds of SwaggerHub users to better understand how they’ve scaled their design process across multiple teams, and a growing number of APIs.
One user, Cameron Befus, VP Engineering at CrowdFlower, explains his experience of moving from the open source Swagger tools to SwaggerHub for more scalable API design:
"Crowdflower has been using Swagger to define our APIs for some time, and that process has become significantly easier thanks to SwaggerHub. Having great tools like Swagger and SwaggerHub that promote collaboration when designing new services — and makes documenting and integration testing those services much easier — is a huge help to our team."
Scot Hastings, CIO of Bonotel, also shared his experience of launching a new design process for a recent API project:
"As we advanced further into the project, we realized we needed to speed up the process and make it more efficient. We wanted to auto-generate the user interface and facilitate collaboration among our internal and external teams without hassles or communication issues… By giving us the ability to design and develop RESTful APIs faster, we can go to market with new services and service updates sooner,” Hastings says. “That makes SwaggerHub a key cog in our software development lifecycle."
Organizations like CrowdFlower and Bonotel have been able to scale their API design by standardizing on OpenAPI for API design, and adopting a tool that seamlessly fits into their API workflow and empowers them to more effectively collaborate on their API design in SwaggerHub.
And they also have represented some of the key principles we’ve seen from teams that have successfully scaled their API design process.
Ready to scale your design process? Here are a few important steps you’ll need to take:
1. Align Your Team
Good API design relies on effective coordination between all the stakeholders involved in the API development lifecycle. If your team is not aligned on the design requirements, or if the right people aren’t able to get the necessary visibility into design changes, you will run into friction when you attempt to scale beyond a small set of APIs. One common way organizations attempt to align team members on the design process is through collaboration tools like Confluence or GitHub.
But while these tools have a critical role in the software development lifecycle, they can be complicated to configure for the specific use case of managing your API design workflow.
Within SwaggerHub, you can create organizations and invite team members to collaborate on the design and documentation of your APIs. Each organization can have multiple teams depending on their role in your API lifecycle. The owner of the organization can assign roles to team members and manage access, based on their involvement in the design process. Learn more about collaborating in SwaggerHub.
2. Improve Visibility into the Design Process
Like the alignment challenges that teams can face when attempting to scale their API design process, there is also the difficult task of improving visibility across your team. Often, we see that teams will start their API design journey with the open source Swagger tools – like Swagger Editor and Swagger UI.
And while these tools offer the capabilities needed to effectively model and visualize APIs, they are not built to foster the collaborate requirements of large API teams. If you’re using OpenAPI to handle your API design, you’ll want to provide a central place for your entire team to access the work that’s being done to design your different services. You’ll also want to ensure that the right people are being notified when changes take place and that you’re not limiting your visibility to disparate emails, Slack messages, and GitHub tickets.
3. Reduce Dependencies
Dependencies across teams can be one of the biggest factors slowing down teams that want to move beyond design to start generating code, drafting documentation, and writing test cases. One of the ways that teams that can reduce dependencies enable faster development is through API “mocking” or virtualization. You can create a mock automatically when creating a new API in SwaggerHub, or you can create it manually any time later.
The mock helps you test your API when designing it, that is, before it is implemented by developers. Also, this integration lets the client application developers start working on their part even before the back end is ready. Without writing a line of code, you can allow API consumers to develop clients against the mock, which is guaranteed to respond with compatible, realistic payloads. More importantly, you can tune the payloads directly in the OAS Definition by using the “example” construct. Learn more about mocking in SwaggerHub.
4. Set and Enforce Design Requirements
A company’s investment in APIs is a long-term endeavor. Design standards don’t just improve implementation of APIs, but also dictate how APIs are updated, or how new APIs are developed. Once design guidelines are set, it’s easier to build off them and allow teams to develop APIs, allowing organizations to scale their design and development process. Since the design defines how clients and services interact, having differences in designs leads to confusion and overhead during the development phase of your services. These inconsistencies only multiply, and their effects will amplify across the API lifecycle.
One way that SwaggerHub helps address the issue of design consistency is with our built-in Style Validator, to check if your API definition matches certain description standards. For example, your company’s guidelines may require that all the properties have examples specified. Style Validator helps you automate such checks. Learn more about standardizing design in SwaggerHub.
5. Improve Reusability in Design
One of the things we often hear from API teams that are working with the Swagger tooling, and OAS to define their APIs, is that the design process can be extremely tedious when defining multiple endpoints across hundreds of APIs. The need to repeatedly define every single endpoint separately can slow down the design process, and lead to inconsistencies in API designs.
That’s why SwaggerHub introduced the concept of Domains to the design process. Domains are reusable components that can be shared between multiple APIs and other domains. A domain can contain the following components: definitions, path items, parameters, responses. Learn more about design reuse in SwaggerHub.
6. Integrate with the Tooling You Trust:
Being able to move quickly from design to documenting, building, and deploying the API is critical for establishing a scaling API design process. Even the best design standards won’t help you scale your API design if there is friction when you start to move beyond that initial phase. One of the ways that API vendors have attempted to address this issue is by building additional design capabilities on top of tools, which are more geared toward API management. While it’s great to have one all-in-one solution, it also requires organizations to be locked into a single solution without much flexibility when you want to introduce new tools.
In SwaggerHub, we have taken a different approach — building a world-class API design platform for teams to use as the “source of truth” for their API design process, and then offering seamless integrations to the tools your team trusts to deliver great APIs, including: API gateways like Apigee, AWS, Microsost Azure, or IBM API Connect, source control platforms like Bitbucket, GitHub, and GitLab, and testing tools like SoapUI for functional testing.
Learn more about SwaggerHub API lifecycle integrations.
Optimize Your Workflow in SwaggerHub
SwaggerHub offers flexible plans for teams of all sizes. Store all your OAS assets in one central location, setup and manage teams, and collaborate across the lifecycle of your API. Available in the cloud or installed within your firewall with our Enterprise solution.
Get started today! Start your free 14-day trial of SwaggerHub, or reach out to the team directly to learn more about our enterprise solutions you can schedule a demo here.