APIOps: are you ready for more tech buzzword bingo? On a serious note, the [Kusk](https://kusk.kubeshop.io) team at Kubeshop has been working with an APIOps mindset for a long time, way before it was trendy. And we’re in excellent company – the folks at [SmartBear](https://smartbear.com/blog/embracing-an-api-design-first-approach/), behind the [Swagger](https://swagger.io/) project, exemplify this approach of ensuring that everyone on the team is speaking the same language when it comes to workflow APIs. APIOps means you can build faster, more robust services and provide an outstanding developer experience, both for the teams building the APIs and the ones consuming them.
Here we explore what APIOps is and how we use the OpenAPI standard as a way to implement an API-First & Design-first approach to development of new workflow REST APIs. Then we will explore some of the challenges of deploying these APIs to Kubernetes and how Kusk can use this approach to simplify both design and operations for API teams.
What is APIOps?
<p>You’ve heard of DevOps and GitOps, now we’re starting to apply these principles to the API and microservices lifecycle. This means standardizing the way we build APIs to ensure that the same high quality and specifications are present in every service.</p>
Just like with DevOps, automating resources for APIs can greatly reduce build-time, speed up debugging and ensure that every service is consistently high-quality. APIOps also enables you to identify any services that aren’t following your standards, so you can quickly patch issues and keep deployments flowing.
What is API-First?
<p>It is tempting to start with developing an application and then designing an API late in the process to expose what was previously developed to the world. As our development platforms grow more diverse, teams face the challenge of supporting a growing number of clients, where the APIs we expose become the primary interface to our application.</p>
Given this shift, many teams have begun to take an API-First approach to development, where the API is a “first-class” experience that is designed from the beginning with development of multiple clients in mind.
This not only improves the development experience for all teams involved, but also works well with a Design-First approach that allows for rapid prototyping, and iterative development that enables more collaboration between teams.
We believe this approach unlocks the benefits of designing up front, but it also means that the design process is so fundamentally central to building APIs that it becomes key to the implementation.
Our very own Kyle Hodgetts, Cloud Engineer, discussed how API-First and Design-First approaches aid in the development process in a [recent blog](https://kubeshop.io/blog/design-first-apis-meets-devops-automated-configuration-for-the-masses), and we couldn’t have put it any better:
Before starting to build your APIs, you define them in a way that everybody can understand; be that human or machine, techie or not. This workflowdefinition provides clear and unambiguous documentation and acts as the “source of truth” for all aspects of your API.
The OpenAPI Specification
<p>For us, APIOps and API-First go hand-in-hand with the OpenAPI Specification, which defines a standard, language-agnostic interface to REST APIs. We actually center our own API workflows with OpenAPI at the heart, as a single source of truth for both function and operations, so we can do away with additional configuration files.</p>
An API definition describes both functional and non-functional aspects of an APIs behavior, including information like:
- Endpoint URLs
- Actions that each endpoint provides in the form of HTTP methods (GET, POST, etc.)
- Expected arguments (if any)
- Example responses
- Non-functional traits; Security Policies, SLAs, Rate-Limiting
There are some great things to come out of the OpenAPI specification, but one we reckon is really powerful is validation: the ability to validate your APIs without coding – yep, no coding!
Engineers, and indeed services, don’t need to see the source code to understand the API capabilities. And on the other side, end users can easily interact with the remote service with minimal implementation logic.
Of course, not everything always goes to plan and sometimes you’re hit with an almighty error message when you try to validate an API.
Not only is it frustrating, it can be a nightmare to work out exactly what went wrong.Just take a look at this recent blog from the great folks at [Stack Overflow](https://stackoverflow.blog/2022/02/28/debugging-best-practices-for-rest-api-consumers/) on debugging best practices for REST API consumers.
When you use the OpenAPI specification, you’re better able to provide meaningful error messages for end users.
And when we can create a smooth ride for developers building and consuming APIs, we can considerably improve the developer experience – that’s really what we’re all about at Kubeshop.
The API Lifecycle
<p>But it’s not just the developer experience that the OpenAPI specification and an API-First approach improves – there’s an entire lifecycle ripe for automation and improvement:</p>
**Mocks** can be generated from the definition before a working backend is even available, for example returning a mock response for any request made to the API. This reduces dependencies between different teams during development, allows for rapid prototyping, embraces a design-first approach to create alignment before coding, and enables better collaboration and more effective API teams.
**User-friendly documentation** can be generated from the definition, and easily integrated into developer portals, etc. so your team can keep moving quickly while ensuring the docs are up-to-date.
There are so many elements to the lifecycle that can be automated — ensuring that whenever the API definition is updated, all downstream artifacts are updated accordingly and always in sync.
APIs and Kubernetes
<p>The world of cloud-native development still lacks tools that apply an API-First approach to embrace Kubernetes and related artifacts. </p>
While an OpenAPI definition could well be the source of truth for a multitude of Kubernetes resources related to deploying an API, you still have to manually set up a ton of finicky things before deploying your API to a cluster – like Ingress controllers, monitoring, security, health-checks, etc. It’s fine when you’re familiar with Kubernetes, but is a serious roadblock to new developers.
We’d rather you spend time designing and implementing APIs than learning new Kubernetes resource formats and keeping those up-to-date as your API evolves. Plus, we don’t want you to have to answer to a frustrated DevOps engineer after tampering with their meticulously crafted helm-charts!
Because we’re all for making developers' lives easier, we wondered: Wouldn’t it be great if OpenAPI could also be used as the true source of truth for operating and managing access to APIs running in Kubernetes?
Automating Resources
<p>[Kusk](https://kusk.kubeshop.io/) automates the generation of Ingress resources for various popular Ingress controllers by treating your OpenAPI Specification as a source of truth.</p>
Working with an APIOps approach, Developer teams can feed the API’s specification to Kusk and have Ingress resources ready to go — always up-to-date with any changes being made by API designers/architects/etc. This can be automated as part of CI/CD pipelines – yay no manual editing! – and is much less error-prone.
As part of the Kusk project, we’ve been working on a self-service API gateway powered by [OpenAPI](https://www.openapis.org/) and [Envoy](https://www.envoyproxy.io/), for teams that specifically develop REST APIs running in Kubernetes and don’t want to spend lots of time configuring Ingress controllers that require a dedicated Ops Engineer, but equally want REST API endpoints traffic to be observable and controllable.
[Kusk Gateway](https://kubeshop.github.io/kusk-gateway/) is an open-source API Gateway that makes your OpenAPI definition the source-of-truth for both functional and operational aspects of your APIs, enabling an iterative API First approach to API development with Kubernetes.
Ole Lensmar recently [wrote about](https://medium.com/kubeshop-i/beta-1-release-of-kusk-gateway-openapi-driven-kubernetes-ingress-controller-bac5d2c03ed8) our beta release and outlined the upcoming roadmap for the project.
The idea behind it is that if we can capture all operational traits in an OpenAPI definition, then we can easily automate API deployment and free DevOps folks up for the really gnarly work involved in managing today’s huge distributed microservices architectures.
Give Kusk Gateway a spin
Head over to the [Kusk Gateway GitHub repository](https://github.com/kubeshop/kusk-gateway) to download the [latest release](https://github.com/kubeshop/kusk-gateway/releases). Installation instructions and documentation are [available there as well](https://kubeshop.github.io/kusk-gateway/). If you have any questions or ideas please feel free to join our [Discord server](https://discord.gg/uNuhy6GDyn) and get in touch.
