Every time your organization needs to create a new API from scratch on Kubernetes, you’re faced with a decision: Are we going to create and follow a process to get this job done, or are we just going to stumble our way into a deployment that we hope gets the job done?
If your organization is mature enough to follow a process, which is a great first step, you also need to decide which route to go. There are a few popular approaches to API design and development, but we’re going to hone in on the design-first approach because it means you’re generating the API’s specifications from the design of your API, not your code. It’s the best way to create APIs that are developer-friendly, go to market faster, and solve everyone’s problems the right way, the first time.
There are big steps to get the job done.
1. Determine what business problem you’re trying to solve
You start by getting the people from technical and business units in the same room (or Zoom call) together to discuss and iterate on how the API should work and validate the design decisions you’re making before anyone even opens up an IDE.
You’ll ask questions like:
- What do we need to get buy-in from customers, leadership, developers, QA testers, and IT operation?
- What kinds of naming conventions or code quality guides should we enforce?
- Which security, authentication, and authorization standards do we need?
2. Codify your API in a human- and machine-readable document
Once you know exactly what your team is trying to accomplish, you can start translating the business requirements and goals into an API definition using OpenAPI, which is the most broadly adopted specification for new APIs. The YAML syntax makes it approachable for technical and business folks alike.
Your goal in this step is to convert your agreed-upon design into an OpenAPI definition, a single document that details exactly how the API works, like the path(s) it responds to, what structure and type those responses should be, what security schemes the API will need, what kind of validation is required, and more.
In the end, this definition becomes your API contract: A single source of truth for how your API works on the frontend, backend, and from the end user’s perspective.
3. Convert the API design into code, tests, and other artifacts using generators… like Kusk!
With your OpenAPI definition in Git, your teams can start writing client- and server-side code that meets those requirements. Or you can use other tools that convert your API into other valuable resources or knowledge:
- With openapi-generator, you can generate client- and server-side code in a variety of languages.
- Tools like portman automatically create tests from your OpenAPI definition
- Complete, up-to-date, and exhaustive documentation that can be generated with Stoplight Elements
- Security verification against known vulnerabilities and remediation advice using tools like 42Crunch
And when it comes to taking an OpenAPI definition to a live Kubernetes deployment, there’s Kusk, an API Gateway that helps you validate, deploy, and monitor your APIs using the open-source and much-loved Envoy Proxy.
With Kusk, developers can annotate existing OpenAPI definitions to add any gateway-related configurations, like CORS rules, cache controls, rate limiting, and much more. Kusk automatically turns that under the hood into an Envoy Proxy configuration, plus the rest of the OpenAPI definition, into a functional gateway that can validate requests and consolidate your error handling.
There’s more — once you’re using Kusk, your frontend developers can use gateway-level mocking to start building the end-user experience while their peers in the backend team work on implementing the API, getting your API to production way faster.
Ready to build your next API with a design-first strategy? Install Kusk and get involved on Discord to learn from others at this exciting intersection between OpenAPI and Kubernetes. The power of the API community awaits…!
Top comments (0)