Co-founder of APIs You Won't Hate, and part techie, part woodland creation, and ancient woodland restoration. Co-founder of @ProtectEarthUK. @philsturgeon@mastodon.green
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
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
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
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
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
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