Skip to main content

Launching API Workflows: make your API standards adoptable

· 4 min read

Writing your style guide and API standards is one of the first tasks teams take on when they start working API-first. We’ve all seen the popular incarnations of these guides from Google or Microsoft. Each guide can be dozens of pages. It is great to have decided upon and written down guidelines, but how do you actually make them easy to follow?

A lot of teams that joined our beta face this “what’s next” problem. They have defined styles, standards and even made hard commitments in their SLAs about when and how API functionality will deprecated. Publishing documentation for your guidelines and expecting them to immediately get adopted is not realistic. It may not even be a fair thing to to ask.

If you want developers to work API-first and follow the standards, you should work to make that easier than the alternatives.

Making the “right way” the easy way.

Optic Workflows helps developers put their team’s API standards into practice. Instead of reading the standards and trying to write OpenAPI that matches, developers can run workflows that help them design the API right, the first time.

We’re already seeing beta users build some really cool workflows that make it easy for everyone on their team to write OpenAPI that follows their team’s standards. Here are some examples:

Make designing standard APIs easy

You could provide a workflow that adds a resource:

optic workflow add-resource User Users

Adds a shared component called User and saves the pluralized version for collection operation paths.

Then run a workflow that adds a list operation that uses the pagination standard:

optic workflow add-operation list Users —-use-pagination

Adds a list operation that references the User component added above, wrapped with your pagination standards.

Maybe you need a series of operations that coordinate a long running process:

optic workflow add-long-running-job NameOfTask

Adds a start, status, and cancel operation and 3 component schemas to fill in for start config, status, and completed.

Make your versioning strategy easy to follow

You could version an operation:

optic workflow new-version post /api/v2/user/{userId}/preferences

Deep copies operation and any $ref'd schemas, renames $refs, and increments path from v2 to v3.

optic workflow update-shared-schemas --allow patch,minor

Checks every $ref that resolves to your JSON Schema registry. Updates the $ref for any patch or minor versions (non-breaking).

optic workflow mark-deprecated get /old/path

Mark an operation as deprecated, and start the countdown to a sunset date. Optic CI checks can make sure any deprecated endpoints that are still around after their sunset date throw warnings.

tl;dr: Make your API standards executable and easy for everyone on the team to adopt.

Why this matters

After Optic launched Optic CI — many API teams realized they could finally go beyond API linting and write the API checks they always wanted in CI. Their CI pipelines can now check for breaking changes, that new surface area meets the API style guide, and that their SLAs are met.

With Optic CI, issues that were slipping through API Reviews were suddenly being caught much earlier than teams were used to. The only way to pass CI was to follow the guidelines. But when all the guidelines are written in markdown, it’s very difficult to figure out how to get your API changes to pass CI.

Optic CI has worked and helped teams enforce things about their APIs they never could before, but it created a new problem. It gave every team “spell check for their APIs”, but without the helpful context menu that suggests how to fix the issue. Imagine if the only way to fix a spelling or grammar error was to figure it out yourself with trial and error?

That’s what API workflows solve: they make it realistic for engineers to follow the standards. Instead of blocking them, Optic Workflows speeds up their work and helps them do the right thing the first time.

Optic helps your team go API-first. Join the beta today.