What is an API?
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). Reports show that the popularity of APIs grew tremendously in 2021 and that trend shows no signs of slowing down.
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 teams to achieve the DevOps workflow, and how Kusk, a tool for generating ingress resources in Kubernetes, can take advantage of this.
What is API Design First?
Design first means that before starting to build your APIs, you chart your API design. You define your API in a way that humans and machines can understand. It places prime focus on the design phase of the API development process. This definition of the API provides clear and unambiguous documentation, among several other benefits, 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.
Anyone interested in reaping the benefits of the design-first approach should browse Stoplight's helpful guide on getting started with it. The team at Smartbear has also published great literature on the advantages of this approach.
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 - like security policies, SLAs, Rate-Limiting
I’ve linked a basic example specification provided by OpenAPI Specification below.
Sample OpenAPI-Specification
Once defined, this can drive a multitude of downstream activities — often — in parallel:
- 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.
What do Operations teams do with APIs?
Operation teams 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, development teams can take ownership of the operations:
- Setting up the points above can be done much earlier and in parallel and prevents blocking the Operations team.
- Developers 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.
API-Code First Approach vs API Design-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 Operations teams at an organization waiting for an initial release to start their work, leaving them blocked.
Developers could have issues discovering the API's functionality and be required to do a lot of manual testing.
This can lead to frustration and result in developers configuring the wrong things for an API.
Kusk: Automate Ingress Resources with a Design-First Approach
Kusk automatically generates Ingress resources for various popular Ingress Controllers by treating your OpenAPI Specification as a source of truth.
Suppose you need an API you need to create Kubernetes Ingress resources and your development team uses a design-first approach.
Developer 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.
