API Evolution for REST/HTTP APIs

There are a lot of pros and cons to various approaches to API versioning, but that has been covered in depth before in API Versioning Has No "Right" Way. API evolution is making a comeback these days with GraphQL and gRPC advocates shouting about it. Whatever API paradigm

Writing Documentation via Contract Testing

Part of my day job is trying to get folks to write API documentation, so the hordes of new developers joining the company on a weekly basis are not stuck trying guess at contracts by poking around years old code. Convincing API developers to take the time to write specs

Getting started with JSON Hyper-Schema: Part 2

Guest post from Aaron Hedges. In my last article I described how JSON Hyper-Schema can describe basic links. This included… * The basics of JSON Schema * Describing links with Link Description Objects (LDOs) * Automating URI construction with URI templates, templatePointers, templateRequired and hrefSchema * Reducing schema duplication with schema references In this

The OpenAPI and JSON Schema Divergence Problem

Update 2020-02-03: OpenAPI v3.1 will be using JSON Schema Draft 2019-09, so tooling vendors should get to work on upgrading support for JSON Schema 2019-09 and the other OpenAPI v3.1 changes. This article is going to explain OpenAPI and JSON Schema divergence, which I’ve been calling the

Creating API Specifications from Bulls**t

So you want to get into design-first API development. Getting started can seem a little tricky, especially when you have a bunch of old APIs floating around and feature work keeps piling up. Writing out full specs for code that already exists can seem like a challenge, and a lot

The Many Amazing Uses of JSON Schema: Client-side Validation

These days type systems are all the rage in APIs, and with gRPC and GraphQL fans touting their baked in systems. REST fans have a few options for type systems, but JSON Schema seems to be powering forwards as the primary candidate. JSON Schema is metadata for JSON, which can

Understanding RPC, REST and GraphQL

Every API in the world is following some sort of paradigm, whether it knows it or not. They will fall under RPC, REST, or a "query language." Even if you are confident you understand the difference, do yourself a favor and read them anyway. About 99% of people

Getting started with JSON Hyper-Schema

Guest post from Aaron Hedges. JSON Hyper-Schema is a format for describing an API. You can automate a lot with a document that describes your API. * API SDKs * Documentation * Tools such as API sandboxes or Postman collections to simplify the development process * Contract tests to ensure your API doesn’t

Ruby Users: Be Wary of Net::HTTP

A few months ago we released We::Call, a Ruby gem that wraps popular HTTP-client Faraday. We::Call aims to configure Faraday with as many best practices for HTTP communications by default as it reasonably can. It’s come a long way over the last few development versions, most of

Keeping Documentation Honest

We've been talking a lot about documentation and API descriptions recently. About how it’s important to write down your contract using API descriptions, and how to turn these descriptions into beautiful human-readable documentation. Now let’s look at how we can ensure that documentation is actually telling

Making the Most of JSON:API

With JSON:API, HAL, and other compound document formats becoming less necessary thanks to HTTP/2, using these formats is no longer a given. That said, there are plenty of reasons for some teams to continue using JSON:API for the near future: 1. Existing APIs with an underlying codebase

Let's Stop Building APIs Around a Network Hack

JSON-API has been one of the most popular standards for API development for a while now. It was conceived in 2013, battled through some rather different RC versions (changing drastically as it went), finally stabilizing with v1.0 back in mid-2015. My interest in JSON-API has changed substantially over the