This article outlines a list of common misunderstandings about REST, so I thought it would be a nice opportunity to set the record straight on a bunch of them. The article is really just 100% misunderstandings, so lets learn some stuff!
Last month today OpenAPI v3.0 was released, and not only is there a lot of cool stuff, but it unblocks some akward situations with vendor prefixes and other lacking features. I was hoping the tooling would be hot on its tails. Progress is being made in all of the repositories I've got my eyes on, but sadly v3.0 support is not there yet.
With endpoint-based APIs you get to choose if you want increased likelihood of network cache hits, or the ability to slim down the response. The two goals are mutually exclusive, but there is a compromise that can be made.
Documentation is a nice thing to have, but it is often treated as optional or superfluous, especially in teams where the clients and servers are managed by the same people. Here the code is considered the contract, so why define it again in documentation?
It's very common for APIs to be treated like "databases over HTTP", with clients expected to infer state from a collection of boolean switches and date fields. Stop this with HATEOAS.
After writing about how GraphQL and REST differ in various regards, and taking a closer look at caching in particular, I wanted to write about how you can get some of the benefits of GraphQL into an existing endpoint-based API.
Recently I wrote GraphQL vs REST: Overview, giving a hype-free outline of the differences between REST and GraphQL. One section that would not have fit into that already lengthy article was caching, so I thought I'd fire that out next.
A few months back I wrote a comparison between RPC and REST for Smashing Magazine, and now I want to talk about the differences between REST and GraphQL: the new kid on the block.
Ignoring one session covering basic CRUD and deserialization using ActiveModel::Serializer, we get to a more interesting session: Handling Errors Nicely.
Now that we've started building a very basic API, we should make sure that the documentation is kept up to date with our progress. Even better, we can use our documentation as a basic contract test, to make sure we aren't lying about what our API offers.