Optic Blog

Make your APIs more consistent using Generic Shapes

Consistent APIs are easier to build, maintain, and (most importantly) consume. As the number of APIs continues to grow, it's important to think about how we're going to make the next 1 million APIs better than the last.

How to change Developer Behavior

Every day billions of lines of code are automatically linted by a fleet of programs running in the IDE and in CI pipelines. The goal is to make source code more uniform, and strip out the bad practices that can be detected with static analysis.

Code linters can be immensely helpful, infuriating, or both — it all comes down to the specifics of the implementation and the ruleset teams choose.

For instance, developers hate linters that are heavy on nit-picky syntax rules. To them, these issues seem small and the linters block progress and make them feel less productive. But those same developers love Prettier and other auto-formatters that accomplish the same goal automatically.

Beneath that example is the guiding principle behind how we think about positively changing developer behavior:

Make correct easier than incorrect, and 'better' quicker than 'worse'

Making API Consistency Easy

The battle to make APIs more consistent is waged during the API design phase. You have to put the right design choices in front of developers, and provide guidance that makes those standards easy to use.

Today we released a new feature in API Designer that makes it easy to codify, reuse and share your API standards. It's called Generic Shapes, and it's an abstraction designed to promote reusability across a single API, and all the APIs at your company.

Let's say your team wants to adopt a standard way to do pagination. Today, your best option for sharing this standard is by writing it up on an internal wiki and enforcing its usage in code review.

In Optic, you would create a new concept that defines generic parameters. From this higher order concept you can compose pagination schemas that work with any other concept in your system.

These higher order concepts can be used like you see below to reuse the pagination boilerplate with any other concept:

You can try out an example with this Pagination example here.

Sharing Standards

In addition to your team's standards, there are a lot of awesome patterns for building REST APIs that are gaining popularity. We built Generic Shapes with Hypermedia, JSON LD, and JSON API in mind. We're working with experts to codify as many of these patterns as possible. We hope we can promote the adoption of these patterns by providing teams with amazing starter templates for designing these kinds of APIs.

If you're interested in helping us with this effort reach out on Twitter @useoptic.

Happy designing! We hope Generic Shapes helps you build better APIs!