Design-first APIs meets DevOps — Automated Configuration for the masses!

Kyle Hodgetts
September 15, 2021

APIs are everywhere. APIs are a standardized way for applications to expose their functionality. API functionality often supersedes that of the UI or Command Line Interface (CLI).

Two distinct paradigms for developing APIs have emerged; design-first and code-first. I plan to cover each, how embracing the design-first paradigm can enable your DevOps teams, and how Kusk, a tool for generating ingress resources in Kubernetes, can take advantage of this.

Design First

Design first means that 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 definition provides clear and unambiguous documentation and acts as the “source of truth” for all aspects of your API.

The OpenAPI Specification is currently the most common way of defining your API specifications, although other mechanisms are available.

Okay, that sounds great! What is an API definition?

An API definition describes both functional and non-functional aspects of an APIs behavior. In a nutshell, it answers the question: “what can I make this API do?”.

It includes information such as (but not limited to):

  • 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

I’ve linked a basic example specification provided by OpenAPI Specification below.

OpenAPI-Specification/petstore.yaml at main · OAI/OpenAPI-Specification

You can't perform that action at this time. You signed in with another tab or window. You signed out in another tab or…

github.com

Once defined, this can drive a multitude of downstream activities — often — in parallel;

Open API Driving the API Lifecycle
  • Frontend and Backend developers can generate stubs from the definition, ensuring they adhere to the defined API
  • Mocks can be generated from the definition to enable testers and developers before a working backend is available
  • User-friendly documentation can be generated from the definition and integrated into developer portals, etc.
  • Deployment/runtime artifacts can be defined (more on that below)

Many of these can be automated — ensuring that whenever the API definition is updated — all downstream artifacts are updated accordingly and always in sync.

Empowering DevOps

DevOps engineers play a key role in supporting APIs.

They maintain the infrastructure the API will run on. They are also often responsible for the following (non-exhaustive):

  • Monitoring and alerting on API metrics
  • Automated testing of the API
  • Setting up Security / Authentication for an API
  • In a Kubernetes context; setting up an Ingress for the API

By employing design-first:

  • Setting up the points above can be done much earlier and in parallel and prevents blocking your DevOps team.
  • DevOps are confident that they are coding and configuring to the specification.
  • They can use automated tools against the specification, decreasing manual work.
  • The API specification becomes a source of truth for testing and configuring supported resources.

Code First

The code-first approach is the more traditional approach; developers receive business requirements and code the API, leaving the formal documentation until later (or most commonly: not at all).

This will result in DevOps teams waiting for an initial release to start their work, leaving them blocked.

DevOps engineers could have issues discovering the APIs functionality and be required to do a lot of manual testing.

This can lead to frustration and result in DevOps configuring the wrong things for an API.

Taking advantage of design-first APIs with Kusk

Kusk automates the generation of Ingress resources for various popular Ingress Controllers by treating your OpenAPI Specification as a source of truth.

Imagine the team developing an API you need to create Kubernetes Ingress resources for has utilized design-first.

DevOps teams can feed Kusk the API’s specification 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 — and means no manual editing and is much less error-prone.

If you’re adopting a design-first approach for your APIs (which you should be!) and are moving into Kubernetes — give Kusk a try and let us know if it does (or doesn’t) help your developers and/or DevOps engineers improve their everyday API development workflows.

For an introduction to Kusk, check out our Hello, Kusk blog post by Ole Lensmar below

Further Reading

Thanks to Dmitry Fonarev.

Get the updates and insights direct to your inbox.