There has never been a better time to be a developer than today. You have access to thousands of articles, millions of Stack Overflow questions, and billions of tweets related to the tech industry. Plus, GitHub just bought npm.

Coding bootcamps are a thing. Websites like A Cloud Guru and Udemy are turning traditional schooling on its head. In short, you have access to what you need if you want to write software.

But, believe it or not, the thing I’m most excited about is the move to open APIs. I can add or manipulate data on pretty much every site or app I use thanks to public-facing, open API documentation. All I have to do is sign up for an API key.

As you build your own software, I’d encourage you to pay it forward. OpenAPI Specification 3.0 is here, and you need to use it.

Why? Good question. Let me tell you.

It’s Industry Standard

Developers don’t actually like working on proprietary things. The only thing proprietary they enjoy working on is business logic — how they solve a unique business problem. But frameworks, custom engines, and sacred-cow patterns on the other hand …

In the fast-paced world we live in today, we have to use things supported by the greater community. We need those Stack Overflow articles, Medium tutorials, or a quick tweet to get the answer we’re looking for.

Photo by LinkedIn Sales Navigator on Unsplash

Gone are the days of tribal knowledge being acceptable. We shouldn’t have to know who to go to in order to figure out who to talk to if we have a problem. We should be able to go to the internet to have our questions answered.

Open API is just this. It’s community backed and has gone through several transformations to get where it is today. Originally an open-source project called Swagger, OpenAPI Specification has come a long way. Now major companies like Google, eBay, and Atlassian all use the spec.

As a developer, you want to learn marketable skills. As a company, you want the ability to hire someone off the street and immediately have them contributing.

This is the gold standard. This is what development practices need to be today.

It’s Your Documentation

Ever heard of markdown? Of course, you have — it’s everywhere. Even if the name doesn’t sound familiar, you’ve seen it. It’s simply a markup language that provides easy text formatting in a plain-text view. And OAS 3.0 uses it everywhere.

You can add professional-quality formatted text descriptions to everything in your spec. Endpoint descriptions, schema definitions, and header and path parameters all get the benefit of having markdown descriptions.

Some people describe self-documenting code as nirvana. Everyone knows that developers don’t like writing documentation. We also know if the documentation isn’t done up front, there’s approximately 0% chance it gets written after the fact.

So having a specification where the documentation lives mingled with the source code is about as close to nirvana as you can get. Writing a new endpoint? Why not throw a couple lines of markdown in there to describe what it’s doing? It only takes a minute, and your spec is going to reap the benefits of professional-quality readability.

It Does Your Validation

Ever get tired of writing the same escape conditions in the entry points of a controller? I feel like I personally have written some mutation of the following code 1,677 times:

if(!event.someProperty || isNaN(event.someProperty)){
    return 400;
}

While this code is simple and repetitive, it’s necessary. But there has to be an easier way than to litter variations of this throughout your web service, right?

Right.

Photo by Matthew Henry on Unsplash

Using an easy-to-consume format, you can define the shape of entities — saying which fields are required versus optional and what their data type is. If you have specific formats for your data, you can even define a regex pattern.

When you have your spec set to validate the headers, path parameters, and body, the validation will sit on top of your API gateway, meaning your code won’t run until it receives a request with valid parameters.

This is great because it means you don’t have to spend your time writing trivial validation code — which means you also don’t have to write those unit tests. This means you don’t have to maintain those unit tests either. Plus, defining the schema in the spec also provides consumers of your API documentation of how the data is shaped.

Adding the request validation to your spec will help increase your productivity and decrease complexity.

If you’re using any AWS serverless services, like Lambda and API Gateway, the validation from OAS 3.0 is particularly helpful because it doesn’t execute your lambda code until after the request validation was run, saving you money from lambda runs.

It’s Extendable

OAS 3.0 already does a lot out of the box. But if you need it to do something specific to your business, no problem. Need it to do something for one of the services you already integrate with? It probably has a documented extension for that, too.

The actual implementation of the extension lives in your code or whatever is consuming the spec. But you can easily just add a new extension to it as long as you prefix it with x-. For example, if I wanted to create a new extension to automatically update my Postman documentation collection, I could declare it in the spec to look something like this:

openapi: 3.0.0
info:
  title: My Example OAS3.0 Spec
  description: Provide a meaningful example for my readers
  version: 1.0.0

x-update-postman-documentation-collection:
  collectionName: Example OAS3.0 API
  autoIncrementVersionNumber: true

In my build pipeline, I can have a lambda function trigger on success that’ll look at the spec, read the extension, then use the Postman API to update the collection I defined.

Note: Extensions don’t show up in the generated documentation, so you’re safe to put whatever you want in them. I’d recommend against adding API keys and secrets into source control, though.

It Talks Directly to AWS Services

Photo by Jason Rosewell on Unsplash

AWS has a full suite of extensions that integrate with API Gateway out of the box. It provides a simple mechanism to tie your spec to real infrastructure and add things like lambda authorizers, request and response transforms, and even proxy to services like DynamoDB and S3 directly. A list of the supported extensions can be found here.

If you use CloudFormation, part of the deploy script reads the AWS extensions and configures your API Gateway appropriately. Whether it’s proxying to various services, configuring CORS, or setting specific integration parameters, it just takes four or fivelines to set up.

In practice, you have your OAS 3.0 spec and your CloudFormation script in separate files. The CloudFormation script references the OAS3.0 spec and sets up everything you have defined at deploy time.

It Pushes Boundaries

You’re a smart person. But chances are you haven’t thought of every single use case for your app. Have you heard of the infinite monkey theorem?

Photo by Jolanda van der Meer on Unsplash

A monkey hitting keys at random on a typewriter for an infinite amount of time will almost surely type any given text, like the work of William Shakespeare.

In this metaphor, you’re the monkey. Given an infinite amount of time, you probably will come up with all the use cases for your API. But we don’t have an infinite amount of time.

Let’s split that time up across an infinite number of developers. Now we’re talking about discovery at scale! If your API is public, people will almost surely come up with ways to use your software you never would have thought of.

Keeping it open allows innovation at scale. Don’t stifle innovation by keeping your endpoints a secret.

Start Now

It’s time to make the world a better place. Amid the chaos of the COVID-19 pandemic, we’re seeing opportunity like never before to give back and help out our communities.

While making your API public might not seem like much, it enables other developers to make integrations and automations that otherwise would have been impossible.

Help drive real change by providing the means to make a difference. Open up your APIs. Contribute to others. We’re all on the same team.

Good luck, have fun, and make an impact!