How SwaggerHub Helps Your API Development Program Scale

People in technology love scale.

It’s the best problem to have when you reach a point where thousands of end users love the products or services you’ve built. But systems need to scale to accommodate your growing user base. This is true in the world of APIs just as it for any other product.

In a small team of 5-10 people with a handful of APIs, it’s not difficult to get all of your team members into a room, chalk out a plan, and start building out your APIs. It’s easy to discuss your plan and goals, and come up with a well thought out structure of development for your APIs. But this style of work isn’t scalable, especially in the software development world of distributed teams, dissolving borders, and cross-cultural collaboration.

Fundamental to the idea of scaling is aligning your people and processes with your standards and tools. The way you choose the right people, and define processes that keep them and their workflow intact, can be a determining factor in the success of your API programs. But managing processes can be extremely difficult.

We built SwaggerHub with this exact goal: to provide an easy-to-use Platform for API teams to work better together as they scale their API development, while providing a central source of truth to manage their lifecycle processes. In this post, I’d like to share key takeaways from organizations that have seen success launching, and Scaling their API programs.

1. Define your goals

Setting a clear vision and mission for your API programs is of the utmost importance. A common mission aligns all your stakeholders on your objectives, especially as your teams become larger with complex personalities and differing skill sets.

Ask yourself why you’re really building your API program in the first place. Is it to enable Digital Transformation of your legacy systems? Is it to expose some of your existing data to third parties for some sort of strategic growth initiative? Is it to have all your internal teams working faster with reusable, interoperable data transfer? Or maybe you’re adopting an API First approach to remain competitive in an increasingly dynamic and fast-moving industry.

These are just some of the many goals an API program can help with. Many times, large teams are riddled with mistrust and animosity due to the lack of transparency. So once your goals are set and you’ve got buy-in from senior management and the powers that be, socialize it with your team.

2. Establish your technology standards

Standards create a common playing ground for your team members to work better together. Standards are like language. They help all your teams have a common Framework of thinking to work on their projects and translate them across other teams and projects. When it comes to APIs, some common standards you’ll need to think about include:

Architectures and Protocols: Protocols are abstraction layers of communication of shared services, and architectural styles help standardize usage of protocols for various inter-system and web communications. REST and RPC are two very prominent examples of architectural styles. RESTful APIs, with their use of uniform and predefined sets of stateless operations over HTTP are more attractive in the present day over RPC architectures using the SOAP protocol. SOAP APIs however, expose their own arbitrary set of operations, including HTTP or SMTP.

Description formats: API formats or specifications define a common vocabulary for understanding your APIs. Typically, it’s expected that these formats are machine and human readable. WSDL is the main description format for SOAP APIs, and the OpenAPI Specification has become the de facto standard for defining RESTful APIs.

Programming: Your backend, frontend and architectural standards should also help you define a standard system of constraints for your programmers to work in. This could include programming languages like Ruby, Python or JavaScript, to architectures like Serverless and Microservices.

Design and Documentation: A scalable API strategy 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.

3. Define your processes

Processes string together your standards and goals into one sustainable API program. Processes help set your governance strategy to ensure any APIs that are delivered follow an accepted set of guidelines, quality and ease of use. Enterprise architects often have the difficult job of establishing and enforcing these processes. These processes are unavoidable when teams grow, and if done right, help streamline development and delivery. Here are some of examples of the types of processes that will help your program scale:

The alignment process: This is how a company or team makes sure every stakeholder is aligned when a new API proposed. Typically, this would include creating a proposal for a new API, reviewing this proposal with the right stakeholders, and making sure the proposal gets buy in from all the key players.

The development process: Once the proposal is reviewed, and stakeholders are aligned on the objectives, the development of the API ensues. Popularly, there are two main types of approaches to developing APIs from a high level – Design First and Code First. The Code First approach is a more traditional approach to building APIs, with development of code happening after the business requirements are laid out, eventually generating the documentation from the code. The Design First approach advocates for designing the API’s contract first before writing any code. This is a relatively new approach, but is fast catching on, especially with the use of the OpenAPI definition format.

The collaboration process: Individuals form teams, and it’s essential they work together with the least amount of friction or confusion. But this process can be hard, especially with distributed teams. It gets even harder when using tools that are great for certain use cases but aren’t meant to collaborate on APIs, like GitHub or Google Docs.  APIs deserve a first-class treatment, which is why tools like SwaggerHub exist to ensure collaboration across geographies and timezones can happen in the easiest way possible. SwaggerHub is equipped with team management and member permission capabilities, so only the right stakeholders can view or edit the right APIs.  
The review process: This is for checking whether APIs that have been developed comply with the development, design and documentation standards you’ve set for your team. Sometimes, key stakeholders need to ensure the right changes get added to APIs without breaking any existing functionality during the collaboration process. Having the ability to review, approve, and merge changes is critical for maintaining a smooth, error-free workflow. SwaggerHub’s compare and merge feature can also help in the review process by allowing API owners to approve changes before they get merged into the main API.

The maintenance process: Once your APIs have been delivered and exposed through an API management platform, work with devops, IT and support to maintain the API. The process is greatly serviced by having a good cataloging infrastructure like you’ll find in SwaggerHub to allow your consumers to find the latest and greatest version of the API, and effectively integrate with them. Investment in a solid Developer Portal, and an inherent mechanism of taking feedback, and updating the API can help you constantly self improve your API program for the best developer satisfaction.

4. Implement the right tooling

Executing your API strategy properly depends on your ability to pick the right tooling to implement various aspects of the API lifecycle. Different tools can help accelerate different parts of your lifecycle. When choosing tooling, make sure they

  • Support open standards and don’t get you locked in
  • Can easily support your existing processes, or allow teams to transition into a better process

Tools like SwaggerHub help you provide a common source of truth for your API definitions, with integrations into the other API tooling your team trusts to deliver APIs, and built-in functionality to effectively enforce standards, improve Resource reusability, coordinate feedback, and organize your team.

Another piece of infrastructure you require for your team is an API management platform. This is a space where some of the biggest and most trusted names in the technology space play, and you’ll need to evaluate these platforms based on the standards and processes outlined above. Some of the most well-known enterprise API management platforms include Apigee (acquired by Google in September 2016), Amazon API Gateway, IBM API Connect, and Microsoft Azure.

Closing Notes

Scaling isn’t easy. Any API owner is likely to tell you that one of the biggest challenges they’ve ever faced was figuring out the best way to scale their development program. There are many factors that will go into deciding the right solution, and there’s no right answer that works for everyone. The important thing is to learn from different approaches, intimately understand your existing challenges, and work with your team to get to the best result.

Be sure to read the next API Strategy article: Why the Transportation Market Exemplifies the Need for Vertical API Platforms