Skip to main content

Building a Better API Specification

路 14 min read

Part 1 of our Changelog Specification Series#

We've had several other API tools engage us about using the Optic Changelog Spec in their products so we're going back to the basics with a repost from our July 8th, 2019 Problems with API Specifications. This is where Dev and I first shared Changelogs specs publicly :) Enjoy!

It's been over a year since Dev first came up with the idea to apply CQRS / Event Sourcing to modeling API behavior, and the idea has proven to be very robust. Since publishing the original form of this article, Optic has pivoted from a GUI for API contracts, to a code generator, then to an API spec generator, and finally to the "Git for APIs" tool that it is today. Don't worry -- you've shown us it's working, and we're sticking with it. No big pivots ahead.

React to API Changes with Optic Scripts

路 6 min read

Optic helps teams write and maintain their first OpenAPI specifications. You don't need to get your team on-board to learn OpenAPI or worry about maintaining 10k line YAML files -- Optic takes care of all of that. This is great, because you have your OpenAPI specification, you can tap into the thousands of community-built tools that make building, publishing and testing your APIs easier.

Optic Scripts#

We're proud to announce a new capability in Optic, Scripts, which makes it easy to use the OpenAPI spec Optic gives you with a variety of other tools. Scripts help you share the information Optic knows about your APIs with other systems. Script definitions live inside your optic.yml file and are invoked with the api scripts command. The Optic Scripts feature is included when you add Optic to your API.

Optic on Software Engineering Daily

路 One min read

This week I had the opportunity to talk about Optic on the Software Engineering Daily Podcast. Jeff and I covered a lot of ground -- everything from why API Change Management Matters to how we see APIs intersecting with the low-code movement.

Take a listen or browse the transcript! A big thanks to Jeff for giving our project airtime! If you don't already, please subscribe wherever you get your podcasts.



Speeding towards Optic 9

路 3 min read

With the release of Optic 8.2 a few weeks ago, major improvements were made to both performance, and the reliability of the diff. Version 8.2 is noticeably faster, but the performance still breaks down when a large number of endpoints have been documented or when diffing large JSON Bodies (multiple MBs). We had hoped the improvements in 8.2 would cary us through the end of the year, but some large teams trying to adopt Optic are still blocked by poor performance -- often having to wait several seconds between critical actions.

Optic 8.2

路 3 min read

Today we're launching Optic 8.2.0 鈥 a big push to make Optic much more usable.

Major Improvements#

The Diff UX has been completely redesigned to make creating and updating your specification much easier. (Under the hood) Performance has been 100x faster evaluating large captures (1000s of API Requests) (Under the hood) snapshot tests now verify the diffing logic at the core of Optic, catch regressions, and help us develop more confidently. Our new process for fixing diff bugs requires us to add more use cases to these test suites so that all fixes are backed up by tests going forward

It鈥檚 OK to Break Your API

路 7 min read

It's OK to break your API

Great APIs can integrate with anything, but in practice they don鈥檛 integrate with everything. Yet, much of the industry approaches their APIs like a fragile, priceless vase: not to be altered for fear of ruining their value and perhaps breaking it.

Simultaneously, these APIs are integrated with a growing number of real-world applications and systems. APIs connect the Internet to smartphones, sensors, and cars. They allow systems to communicate with each other and businesses to quickly add new features to applications. We want these things to work and they must be able to evolve.

Most organizations today produce more private and internal APIs than public APIs. So, the idea that an API must work for everyone who may use it has become less relevant over time. However, if you build an API, it must still work well for users. And while most APIs have a small number of consumers, changes to an API can lead to startling impacts in the real world.

You can avoid these unexpected consequences when you change your API. All it takes is effective communication and building strong relationships between you and the consumers of your API.