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
Caching is a huge topic, and there’s a lot of different types of caching. No one type of cache is going to suite all needs and cover everything needed to make a performant application, but one type that’s often overlooked is client caching at the HTTP level. Building
API versioning is a really difficult topic, and sometimes seen as a merely religious debate. It’s done differently at different companies, and different teams within different companies often vary. Some folks move from approach A to approach B, and when approach B solves their specific issues they act like
A question that is asked with increasing regularity in the APIs You Won’t Hate Slack Group is one which has been asked for years, but does not always have a good answer. The question is: What is the different between PUT and PATCH, and when do I use them?
Continuing on the topic of contracts — metadata that describes your data — it makes sense to see what easy early wins you can make from this stuff. Having a bunch of files written in JSON Schema, API Blueprint, RAML, OpenAPI, etc is not particularly exciting for developers who understand the format,
When building and maintaining a Web API, it's surprisingly common for the "I" (interface) part to be overlooked. Often new functionality is built in close contact with a specific client, with the backend and frontend developers sitting together to hash out the functionality. The frontend developer
I’ve seen a few people promoting GraphQL and gRPC over REST, almost purely on the merits of being "not JSON”. They moan about JSON and instil the virtues of these architectures for their use of stricter type systems. As well as blaming JSON for various imagined faults, they
With endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) 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. Slimming responses can be achieved with concepts like sparse fieldsets (tl:dr; send
Do you like the look of GraphQL, but have an existing REST/RPC API that you don’t want to ditch? GraphQL definitely has some cool features and benefits. Those are all bundled in one package, with a nice marketing site, documenting how to do all the cool stuff, which
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 cover this on its own. Comparing how caching is used for the