JSON Schema: Good, Bad and Ugly

An interesting thread on BlueSky last week pointed out limitations with OpenAPI, from non-optional parameters to JSON Schema being a validation spec, not a schema.

It's a good read, and gets juicier when Sylvain Wallez jumps into not using OpenAPI for the Elasticsearch API because of JSON Schema. Instead, they use TypeScript definitions to generate an OpenAPI spec for specific tools. Sylvain points out that this is why Microsoft created TypeSpec and AWS created Smithy.

As we all know, there is never one golden perfect solution in tech; everything is tradeoffs, except JavaScript, which is fantastic and has no flaws.

I think there are a few issues here: Optional parameters suggest either a broken approach to API design or that a REST API is not the right fit here. However, the problems with JSON Schema ring a little closer to home, as I have come up against these myself. However, I always push for improving the tools where possible over introducing more competing standards. These conversations are great, though, and help push specs and guidelines forward most of the time.

-- Alexander

The API Round-Up

API News, links, and tools from around the web

The HTTP QUERY Method

A renewed push for an HTTP method called Query, allowing you to include a body in GET requests. Designed to help with complex quries or filtering, moving them out of the URL into the body. It is not a new idea, and there have been versions of it in the past. It will be interesting to see if it makes it into the spec.

Which Go router should I use?

When building an API in Go, which router do you use? The standard library includes one, but there are many third-party frameworks. Taking some of the most popular third-party options, Alex Edwards walks you through the standard library and shows you when to reach for a third party.

The Future of MCP is GraphQL

Everyone is adopting MCP quickly. Apollo has released an MCP server, allowing AI systems like Claud and ChatGPT to interact with GraphQL APIs. Apollo walks you through their setup and explains why GraphQL fits MCP and AI well.

API Versioning in Spring

Spring is rolling out support for built-in API versioning, allowing you to map versions to annotated controller methods. WebClient and RestClient also support the version. It's great to see Spring making API versioning easier.

Migrating from API keys to OAuth 2.1

Using API keys for server-to-server calls? OAuth 2.1 has become mandatory for MCP servers. ScaleKit explains how to migrate to OAuth and how it can make this process easier.

Help shape the future of APIs

If you build, manage, or use APIs, your insights can help highlight key trends and challenges in the ecosystem.

Take the 10 minute survey, and you'll get early access to the report — plus a chance to win a PS5, NuPhy mechanical keyboard, and more!

Take the Survey

APIs You Won't Hate

The latest from the team at API's You Won't Hate.

API Design Reviews Don't Have to be Hard

Do you love staring at YAML files? No? Phil shows you can handle API design reviews in PRs using Bump.sh instead of comparing large diffs in YAML files.

Thanks so much to our members: Kin L, Juxt, Alex R, Nolan S, Frank, James D, Bill D, Rich, Ryan T, and Umair. Your support means the world to us!

Until next time,
Alexander, Phil & Mike