Distribute Spectral Style Guides with NPM

At some point in the growth of an organization there will come a time where you've got too many different APIs with random different data formats, naming conventions, security schemes, and generally it feels bizarre and frustrating trying to call any API because you cannot share any code

The Best Content to Supplement Your API Documentation

I started learning to code over ten years ago. As a self-taught developer, I picked up most of my knowledge from programmers who left breadcrumbs on Stack Overflow or wrote tutorials online. Early in my career, I often found documentation overwhelming. Without enough contextual knowledge, I struggled to turn raw

Modern API Deployment Options in the Cloud

How do you deploy your API, and what's the best way to structure it? Front-end frameworks have come a long way in recent years, making it easy to spin up and deploy a website/web app. However, I find the noise caused by many strong opinions sometimes clouds

Contract Testing a Laravel API with OpenAPI

Your API does a bunch of great stuff, and your OpenAPI document tells everyone about all the great stuff that your API can do, but making sure those two sources of truth agree can be a bit of a struggle at first. Whether you followed the API design-first workflow and

Eight of the Biggest Lies in APIs

Have you ever been told "Everybody does it this way" when arguing about API design? Or have you heard, "We use HTTPS, so our API is secure"? In the API space, numerous statements are highly context-dependent, misunderstandings, or outright lies. To find some of the most

Creating OpenAPI from HTTP Traffic

Around this time of year we're thinking about things we're going to do differently, new practices we've been putting off for too long, and mistakes we want to avoid continuing into another year. For many of us in the API world, that is going

JSON Schema Bundling Finally Formalised

Here we have a special treat, a guest post written by Ben Hutton, JSON Schema Specification Lead at Postman. They are here to talk about the new way in which "bundling" works in OpenAPI, which is the art of turning multiple JSON Schema / OpenAPI documents - linked together

Why Show Users Garbage API Errors?

A million things can go wrong when an API client talks to an API, from the expected to the unexpected, from business logic and validation failures, to dropped connections and race conditions. The server could run out of RAM, the request could time out, an automatic retry might trigger a

There's No Reason to Write OpenAPI By Hand

Some API developers use API descriptions to plan the interface of an API before building it, which is known as the "API design first" workflow. Others build the API then generate (or manually produce) API descriptions later, which is the "code-first" workflow. We wrote API Design-first

OpenAPI v3.1 and JSON Schema

Updated 2019-05-29: OpenAPI v3.1 has dropped SemVer, so a few things that were going to be deprecated are now just straight up removed. This post has been updated to reflect that. Updated 2021-01-10: JSON Schema released Draft 2020-12 which clarified a few edge cases, it's not a

Easy to Follow Hypermedia Controls with Ketting

Hi! My name is Evert, and for a while now I've been working on a project called Ketting, which is a generic Hypermedia/HATEOAS client for Javascript. I just released version 5.0, and thought it might be interesting to share the new features that have been added