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
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