With the slow but sure rise in remote working, let's leverge this fantastic lifestyle change to improve our own quality of life, and avoid perminently flooding the cities millions of us call home.
What does a web application framework need to offer API developers in 2020 in order to meet the demands and keep up with modern practices?
Update 2020-02-02: JSON Schema Draft 2019-09 has been published for a while, and after much deliberation we got the folks at OpenAPI to merge #1977 for v3.1. This will make OpenAPI a small superset, and no longer a subset/superset/sideset. Of those five keywords, two are deprecated (nullable and example). Latest estimate for v3.1.0-RC1 is end of February, so tooling vendors should get to work on upgrading support for JSON Schema 2019-09 and the other OpenAPI v3.1 changes.
Two months ago I teased that Stoplight was about to release something big, and yesterday we announced Stoplight Studio - an OpenAPI and standalone JSON Schema editor, which just so happens to be visually stunning and completely free.
This blog has been a bit quiet for the last two years, with me blogging on APIs You Won't Hate and phil.bike more than here.
A while back I wrote an article called Understanding RPC, REST and GraphQL which outlined the "what" in how these various approaches differ. This got a few people thinking I was saying REST was drastically superior in all ways, which is a common conclusion when folks hear me describe REST as a layer of abstractions on top of RPC… More abstractions does not mean definitively "better", sometimes that's going to be overkill, so let's look at when you might want to use which.
API Evolution is making a comeback these days with GraphQL and gRPC advocates shouting about it. Whatever API paradigm or implementation you subscribe to, evolution is available to you. REST advocates have been recommending API evolution for decades, so let's take a look at how that can work.
Update 2020-02-02: This article has been replaced entirely, as the proposed workaround was written into a now abandoned project Speccy, and the long-term proposed solution "Alternative Schemas" has been punted to a later version of OpenAPI due to complications with the form it took.
This article is going to explain the divergence between OpenAPI and JSON Schema, which I've been calling the subset/superset/sideset problem. It'll finish up explaining how we're going to solve it, and ~I'll write part 2 when it is solved~ part two explains the solution.
Back in October I wrote Chasing the Perfect API Specification Workflow, which was a huge article about the state of the API specification world. One person trying to figure out a good workflow, in a sea of alternative specifications, with incomplete tooling, making it hard to see a solution for all the partial bits of functionality.