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.
Third video in a pile of LiveCoding.tv videos, shows how to use ActiveModel Serializer to shape the output of your resources. I totally forgot how links work, so watch me flap around trying to get it working and chuckle as I flail.
The second video in a pile of LiveCoding.tv videos shows how to use your API Blueprint documentation to mock APIs, and a few different ways of serving those mocks up to people.
Two years ago I finished the first edition of Build APIs You Won't Hate, and since then I've worked on bigger and better projects, using my API experience, honing some approaches, and throwing out some approaches entirely.