Guest post from Aaron Hedges. In the last two JSON-Hyper Schema articles (Getting Started — Part One and Part Two), we covered the basics: * Basic Links * Request and response bodies * Request and response headers * HTTP methods But while working with JSON Hyper-Schema I have discovered a couple of common API patterns
Update (2019-10-04): When I left WeWork I left Speccy with a few colleagues, who have thankfully done a lot of maintainance work. If you like the idea of Speccy but want more power, use Spectral by Stoplight. It has a bunch of developers and community contributors regularly adding amazing features,
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'
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
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 "
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
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
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
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
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
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
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