Surviving Deprecations to Resources and Properties on Other APIs

Deprecation, is the art of telling people to stop using that thing, because that thing is probably going away at some point. Even if there are no solid plans to delete the thing entirely, the thing might be deprecated just because it sucks to work with, but usually it'

Picking the right API Paradigm

This article provides a decision flow diagram for selecting the "approach” to use for your next API. To oversimplify things a bit, it’s reasonably fair to say that all APIs conform to a paradigm: "RPC”, "REST”, or "query language”. These are general approaches to building

What is API Rate Limiting All About?

Something API clients (applications talking to APIs) are not often aware of, but run into often, is rate limiting; the API telling you to calm down a bit, and slow down how many requests are being made in a certain timeframe. The most basic rate limiting strategy is often "

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