Skip to main content

· 7 min read


When I've talked to companies about the way they design and build APIs and ask if they're using a Design First or Code First approach, many will emphatically respond they're Design First—they've decided that every team must update their OpenAPI document before they write a line of code. But when I ask if they have any teams that haven't made the switch and still follow a Code First approach, the truth comes out. "Well, actually, all our teams are Code First at the moment, but we're all moving to Design First."

· 8 min read


Since the early days of Optic, there's always been this tension between inferring API specifications from traffic (how we got our start), and teams wanting more mature "design-first" workflows.

· 8 min read

Documenting your software is as important as developing your software. With maintenance making up 50–70 percent of a system's cost over its lifetime, it's important to be efficient and clear about how the software was built and how it behaves. If human beings are going to maintain the application, you must document your software.

However, it's a tedious and constantly evolving process, which means you need to always make changes to the documentation each time you make a change to your software codebase. But what if you don't have to worry so much about editing multiple documentation files each time you update your code? What if you could just focus on writing great code?

· 3 min read

I'm a big believer that the order you read a set of books can matter more than the books you read. When different ideas and perspectives mix into a savory synapse soup -- good things happen. That was my last 10 days. I've gotten to talk to some amazing people about the history of Swagger/OpenAPI (history matters), why API Specifications matter, and the problems we face building and scaling tools across the wider API Community.

My brain was overloading, so I sat down and did a talk:

Watch the Talk

· 8 min read

According to Gallup, my top strength is Learner. That’s probably the reason I got into software development over two decades ago. Technology changes so quickly, there’s always something new to learn.

Java was the first real programming language I used back then. At the time, it had been around for about three years and was still very immature. But all this time, there’s something that I have always remembered and appreciated about Java: its exceptional API documentation. It was easy to understand, the examples were useful, and it was usually all I needed to solve any problem.

Good API documentation shouldn’t be exceptional, but it is. And it’s important.

· 8 min read

Flowchart example

Design First is a practice that encourages us to design any API change before writing the code code. The goal is to do the upfront work to produce better API changes. Design First is normally done by modifying an OpenAPI document first and then using that change as guidance on what to develop.

But Design First is a small piece to the larger API development process. There are more practices and patterns we need in order to make design a cornerstone to building good APIs.

When taken alone, Design First seems to imply that the process is linear—first there's the design, then development, then deployment. But design doesn't work this way. Design is something we're always doing, even when writing code.

What then are the practices we need to add into our Design First workflows that makes Design First work?

· 4 min read

I’m new around here, and my first post is about something I really love… code that makes life easier!

To begin with Optic's CLI is ridiculously easy to start using within your application, you simply head to the root of your directory and run api init, configure your .optic.yml to wrap your application start command, and tada you’ve started gathering data about your API endpoints by just using them. Super simple and great right? To look at the full process and implement it yourself, please check out our documentation.

But what happens when you can’t do that? Plenty of instances exist where it’s very complex to work in a team and wrap the command that starts your application. What happens when you use feature flags on that command, or you have to make operating system specific changes, or your API testing is done entirely internally and doesn't hit the network?

· 10 min read

Code reviews are an essential part of any high-quality software development process. A thorough code review can prevent bugs and regressions from slipping into production, improve code quality and consistency, and ensure your team knows about important changes before they go live.

While looking at code can help you find flaws in your logic, it's notoriously hard to trace changes through your application to see how they might actually affect your API.