APIs You Won't Hate

All Articles

Featured Article

Eight of the Biggest Lies in APIs

written by Matthew Reinbold

In the API space, numerous statements are context-dependent, misunderstandings, or outright lies. Here are some of the biggest the APIs You Won't Hate community has heard to date.

Read more →
Eight of the Biggest Lies in APIs
Creating OpenAPI from HTTP Traffic

Creating OpenAPI from HTTP Traffic

Phil Sturgeon

Jan 01, 2022

If you want to get into API design-first, but awkwardly already have a bunch of APIs with no OpenAPI, use a HTTP proxy like Akita to create OpenAPI from your HTTP traffic!

JSON Schema Bundling Finally Formalised

JSON Schema Bundling Finally Formalised

Ben Hutton

Aug 04, 2021

Existing tooling developers have created their own approaches to bundling JSON Schema and OpenAPI documents, but that can lead to errors. Bundling is now standardised.

Why Show Users Garbage API Errors?

Why Show Users Garbage API Errors?

Phil Sturgeon

May 14, 2021

What happens in your client application when an API error pops up beyond the common cases of Logged Out, Not Found, etc.? Do you vomit random API error codes and exception class names all over your end users screens, pointlessly confusing the hell out of them?

There's No Reason to Write OpenAPI By Hand

There's No Reason to Write OpenAPI By Hand

Phil Sturgeon

Mar 30, 2020

Sometimes you see people complaining about OpenAPI (formerly Swagger), saying they don't want to to write out a whole bunch of YAML/JSON by hand. Other than disability, there's no reason you need to do that, and there hasn't be for a long time. Whether you pick code-first or design-first, you've got some options.

OpenAPI v3.1 and JSON Schema

OpenAPI v3.1 and JSON Schema

Phil Sturgeon

Feb 03, 2020

JSON Schema and OpenAPI will no longer have minor differences in the schema object, but will finally be compatible from OpenAPI v3.1.

Easy to Follow Hypermedia Controls with Ketting

Easy to Follow Hypermedia Controls with Ketting

Evert Pot

Nov 22, 2019

The Ketting library is a generic hypermedia client written in JavaScript. It supports an opinionated set of modern features REST services might have, including HAL, JSON:API, Web Linking (HTTP Link Header) and HTML5 links. Ketting v5.0 just released with support for Siren and other neat new features.

Automated Style Guides for REST, GraphQL and gRPC

Automated Style Guides for REST, GraphQL and gRPC

Phil Sturgeon

Nov 05, 2019

Create API style guides using linting tools for any API paradigm. Avoid "API Governance" teams sitting there reviewing every single API change that comes through, and automate that menial task away to the bots.

OpenAPI Callbacks and Webhooks

OpenAPI Callbacks and Webhooks

Lorna Mitchell

Oct 24, 2019

What's the difference between a callback and a webhook, and which does OpenAPI support? Read on to find out the current status and upcoming changes for asynchronous and two-way APIs.

API Design-First vs Code First

API Design-First vs Code First

Phil Sturgeon

Oct 14, 2019

With API descriptions rising in popularity, the main question I hear folks asking about is "API Design-first" or "code-first". This is a bit of a misleading question because these are not two unique things, there are a few variants.

GraphQL & Caching: The Elephant in the Room

GraphQL & Caching: The Elephant in the Room

Marc-Andre Giroux

Jun 25, 2019

Bringing nuance to the polarized subject of caching in GraphQL.

Testing API Client Applications

Testing API Client Applications

Phil Sturgeon

Jun 09, 2019

Got some code that talks to a Web API and want to make sure it works properly? Here's a bunch of options you can use to mock external dependencies.

Server-Side Validation with API Descriptions

Server-Side Validation with API Descriptions

Phil Sturgeon

May 25, 2019

Why waste a bunch of time duplicating validation rules in your application code and API description documents, then waste even more time trying to make sure these two disparate sources match up? Save a bunch of time and avoid mismatch bugs by using your API description as production code, so you have one source of truth, and your existing test suite can do the job of making sure things work.

REST and Hypermedia in 2019

REST and Hypermedia in 2019

Phil Sturgeon

May 17, 2019

A modern day look at the Richardson Maturity model, and insight into how the various layers of abstraction REST provides can help API Developers working in HTTP for various scenarios.

PKCE vs Proxy

PKCE vs Proxy

Grant Callaghan

May 11, 2019

It all comes down to what you can protect and where you redirect.

Creating Good API Errors in REST, GraphQL and gRPC

Creating Good API Errors in REST, GraphQL and gRPC

Phil Sturgeon

Apr 16, 2019

Dealing with the Happy Path™ in an API is pretty easy, but creating useful error messages can be tricky at first.

Resolving Overloaded Terms for API Specifications… Descriptions… Contract?

Resolving Overloaded Terms for API Specifications… Descriptions… Contract?

Phil Sturgeon

Apr 04, 2019

Specifications, Descriptions, Definitions, Spec Files, Contracts, ugh… they’re the same thing!

Caching is hard, draw me a picture

Caching is hard, draw me a picture

Phil Sturgeon

Mar 28, 2019

Another guest post from our friend Darrel Miller, this time explaining caching.

Organizing your AsyncAPI documents

Organizing your AsyncAPI documents

Phil Sturgeon

Mar 01, 2019

Split your AsyncAPI documents into multiple files with $ref.

Optimizing for the Speed of Light

Optimizing for the Speed of Light

Phil Sturgeon

Feb 24, 2019

Written by Darrel Miller, on his blog Bizcoder.com

Taking a Timeout from Poor Performance

Taking a Timeout from Poor Performance

Phil Sturgeon

Jan 03, 2019

In a system-oriented architecture, it is crucial to communicate with other systems, sometimes synchronously. Broker patterns, proxies, etc., or even just a remote procedure being triggered synchronously, like confirming an email has been sent successfully.

WeWork’s API Specification Workflow

WeWork’s API Specification Workflow

Phil Sturgeon

Aug 28, 2018

One source of truth: API Specifications, and get docs, mocks, testing, and more.

Common Hypermedia Patterns with JSON Hyper-Schema

Common Hypermedia Patterns with JSON Hyper-Schema

Phil Sturgeon

Jul 28, 2018

But there are a few objectively terrible ways to handle it.

Govern your APIs with Speccy

Govern your APIs with Speccy

Phil Sturgeon

Jul 23, 2018

The last year has involved a lot of teaching engineers how to use OpenAPI, with the day job growing from a startup to a sizeable…

Surviving Deprecations to Resources and Properties on Other APIs

Surviving Deprecations to Resources and Properties on Other APIs

Phil Sturgeon

Jun 03, 2018

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…

Picking the right API Paradigm

Picking the right API Paradigm

Phil Sturgeon

May 21, 2018

This article provides a decision flow diagram for selecting the “approach” to use for your next API.

What is API Rate Limiting All About?

What is API Rate Limiting All About?

Phil Sturgeon

May 16, 2018

Learn what rate limiting is all about, and how you can train your HTTP client code to handle being limited.

API Evolution for REST/HTTP APIs

API Evolution for REST/HTTP APIs

Phil Sturgeon

May 02, 2018

API Evolution is making a comeback these days, and REST advocates have been begging folks to use it for years. Let's learn how.

Writing Documentation via Contract Testing

Writing Documentation via Contract Testing

Phil Sturgeon

Apr 19, 2018

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…

Getting started with JSON Hyper-Schema: Part 2

Getting started with JSON Hyper-Schema: Part 2

Phil Sturgeon

Apr 04, 2018

Let's learn a bit more about JSON HyperSchema, building on the foundation in part one, with resource representations, arbitrary request bodies, HTTP headers, and HTTP methods.

OpenAPI and JSON Schema Divergence

OpenAPI and JSON Schema Divergence

Phil Sturgeon

Mar 30, 2018

This article is going to explain OpenAPI and JSON Schema divergence, which I’ve been calling the subset/superset/sideset problem. There are some plans to fix it, but they're a way off.

Creating API Specifications from Bulls**t

Creating API Specifications from Bulls**t

Phil Sturgeon

Mar 09, 2018

So you are using design-first for new APIs, but what about old APIs? Play catchup with a few sneaky methods.

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

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

Phil Sturgeon

Feb 05, 2018

These days type systems are all the rage in APIs, so lets see how HTTP APIs can use JSON Schema for client-side validation.

Understanding RPC, REST and GraphQL

Understanding RPC, REST and GraphQL

Phil Sturgeon

Jan 04, 2018

Every API is following some sort of paradigm, whether it knows it or not. Learn the differences, for when you talk to other APIs.

Getting started with JSON Hyper-Schema

Getting started with JSON Hyper-Schema

Phil Sturgeon

Dec 22, 2017

JSON Hyper-Schema is a format for describing an API. You can automate a lot with a document that describes your API.

Ruby Users: Be Wary of Net::HTTP

Ruby Users: Be Wary of Net::HTTP

Phil Sturgeon

Dec 14, 2017

We discovered some fairly interesting behaviors in Net::HTTP recently, and figured we better share them.

Keeping Documentation Honest

Keeping Documentation Honest

Phil Sturgeon

Nov 21, 2017

We've been talking a lot about the importance of documentation and API descriptions, Now let’s look at how we can ensure those descriptions are actually telling the truth!

Making the Most of JSON:API

Making the Most of JSON:API

Phil Sturgeon

Oct 30, 2017

If you absolutely positively have to use JSON:API for your API, here's how to make it work well for you.

Let's Stop Building APIs Around a Network Hack

Let's Stop Building APIs Around a Network Hack

Phil Sturgeon

Oct 21, 2017

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...

Speeding Up APIs/Apps/Smart Toasters with HTTP Response Caching

Speeding Up APIs/Apps/Smart Toasters with HTTP Response Caching

Phil Sturgeon

Oct 12, 2017

Caching is a huge topic, and there’s a lot of different types of caching. No one type of cache is going to suite all needs and cover…

API Versioning Has No "Right Way"

API Versioning Has No "Right Way"

Phil Sturgeon

Sep 26, 2017

But there are a few objectively terrible ways to handle it.

PUT vs PATCH vs JSON-PATCH

PUT vs PATCH vs JSON-PATCH

Phil Sturgeon

Sep 25, 2017

What is the difference between them?

Turning Contracts into Beautiful Documentation

Turning Contracts into Beautiful Documentation

Phil Sturgeon

Sep 22, 2017

Continuing on the topic of contracts — metadata that describes your data — it makes sense to see what easy early wins you can make from…

Commit to API Contracts

Commit to API Contracts

Phil Sturgeon

Sep 16, 2017

When building and maintaining a Web API, it's surprisingly common for the "I" (interface) part to be overlooked. Often new functionality is…

Why Do People Dislike JSON?

Why Do People Dislike JSON?

Phil Sturgeon

Aug 26, 2017

People seem to be moaning about JSON when they really just are upset with unspecified data.

Partials: Happy Compromise Between Customization and Cacheability

Partials: Happy Compromise Between Customization and Cacheability

Phil Sturgeon

Aug 13, 2017

With endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) you get to choose if you want increased likelihood of network…

You Might Not Need GraphQL

You Might Not Need GraphQL

Phil Sturgeon

Aug 12, 2017

Do you like the look of GraphQL, but have an existing REST/RPC API that you don’t want to ditch? Here's how to get those benefits without rewriting it.

GraphQL vs REST: Caching

GraphQL vs REST: Caching

Phil Sturgeon

Aug 12, 2017

Outlining the approach the two API paradigms take to caching.

Representing State in REST and GraphQL

Representing State in REST and GraphQL

Phil Sturgeon

Aug 12, 2017

Learn how an API can become a state machine, with different actions appearing for resources in different states.

GraphQL vs REST: Overview

GraphQL vs REST: Overview

Phil Sturgeon

Jan 24, 2017

An objective overview and comparison of REST and GraphQL, despite it being rather strange to try and compare a paradigm and an implementation.

Get the newsletter

Pragmatic API, HTTP And REST info monthly