API Design and Microservices: Insights from Conversations with 500 API Developers

  April 26, 2017

The SwaggerHub team recently traveled to Austin, TX for DockerCon 2017. DockerCon is the world’s largest container technology conference, bringing together more than 5,000 Developers, DevOps, System Administrators, and others from across the Docker community

What brought us to DockerCon this year?

Over the last year, we’ve seen a tremendous growth in adoption around the SwaggerHub platform from software teams that are making the investment into microservice architecture. Over the course of three days, we had the chance to have hundreds of conversations with people at different stages of their microservices, and API adoption journey. It was great to hear from so many that are using Swagger tooling, and the OpenAPI specification to help with the implementation of their microservice architecture, and to learn more about how we can continue to evolve SwaggerHub to help address the needs of API teams. As a followup to this year’s event, we wanted to share some of the key insights we learned from our conversations at DockerCon 2017.

1. The OpenAPI (Swagger) Specification has an important role in the move to microservices

Organizations that make the shift from monolithic applications to microservice architecture,  usually rely on APIs to expose services to communicate with each other. To better expose services via APIs, a common interface for these APIs needs to be present to tell exactly what each service is supposed to do. The OpenAPI (Swagger) Specification (OAS)  has emerged as the standard format for defining this contract, providing a common interface that defines the SLA between the client and the services, in a way that’s both human and machine readable. For the teams we spoke with throughout the week at DockerCon, the primary use case for defining their APIs with OAS is to generate the necessary documentation for internal teams to work with their APIs, with Swagger UI as the most popular implementation of the spec.

2. Most teams still follow a “code first” approach to API development

A lot has been written about the benefits of a design first approach to developing APIs, or building microservices. The design first approach involves designing and defining the interface of the microservice first, reviewing and stabilizing this contract, and then implementing the service But while design first may be ideal, most teams we talk to are still following a code first approach, where they are using some combination of open source tooling to generate Swagger files from existing APIs — either in runtime or build time. For most of the people we talked to, the decision to follow a “code first” approach to Swagger is that it can be implemented much quicker than moving to a design first approach.  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.   Learn more: [Free Download] How to Add Swagger to an Existing API

3. Style consistency is a growing problem for API teams

Regardless of the architecture your team uses to implement software systems, if your team is serious about good API developer experience, you likely have some guidelines for your team to follow. But when we spoke to individuals about how they are enforcing these guidelines, it was obvious that there is still room for improvement. Four of the common trends we heard from our discussions were:

  • Keeping track of all the Swagger files being worked on
  • Handling versioning of existing APIs
  • Enforcing style guidelines across an entire team of developers
  • Making it easier to reuse common design objects across multiple services

SwaggerHub was built to address these challenges, by providing a central place for your entire team to work across the lifecycle of your API with Swagger while driving API design consistency and reusability using domains and Style Validator. The Style Validator ensures your RESTful interface adheres to a standard blueprint based on your organizational requirements. This could mean ensuring all interfaces have camelcase operators, examples defined in their response packets, or have their models defined locally. In Domains, you can store common, reusable syntax, be it models or request-response objects, that can be quickly referenced across multiple APIs that expose your microservice business capabilities.

4. API Management solutions have an import role in microservice architecture, but design is a much-needed solution

API management solutions have an important role in the orchestration of microservices. With mechanism for security, monitoring, analytics, and discovery — these platforms help handle the multitude of APIs as part of your microservice architecture. But while many API management solutions offer design capabilities, the need for dedicated toolset for API design, also becomes clear. Good API design is important for any public or private-facing API. As one Swagger user put it during a discussion at our booth: “you need to offer the same quality experience to internal teams working on your APIs, as you would external developers.” When you’ve set your style guidelines, you need a tool that will provide a first-class treatment for the design of your API. For teams early on in their journey with Swagger, an open source tool like the Swagger Editor can provide the necessary tooling to write and update definitions. For advanced teams that need to seamlessly integrate design with their API management platforms, a fully-integrated platform like SwaggerHub can help.

5. API teams need a better way to host and manage API docs

Whether you’re using APIs to expose services publicly, or within your own software architecture, it’s important to have documentation that is up-to-date and easily accessible. This is the biggest reason why we hear teams get started with implementing Swagger in the first place. But when your API docs go from a few different versions within one team to tens or even hundreds of different APIs, maintaining those docs can be a problem. One common solution we hear from Swagger users is to host documentation on source control hosts like GitHub or Bitbucket. But while these tools are great for hosting source code, they still don’t make it easy to easily access all the different docs you have available from one central place. As a result, most teams will find an internal solution instead. We’ve worked to provide an alternative solution in SwaggerHub, letting you host and maintain all of your API’s documentation from one centrally hosted platform. SwaggerHub can act as your organization’s internal API catalogue, with the ability to manage privacy, publish and unpublish versions, and even host on your own servers with our Enterprise plan. Learn more here. Thank you to everyone who stopped by the SwaggerHub booth at this year’s DockerCon event! If you’re interested in getting started with SwaggerHub, you can sign up for free right here. Or reach out to the team to get your questions answered: [email protected]