[yashap]

We edit the OAS with Stoplight Studio, and enforce it with server-side middleware, which validates that requests and responses conform to the OAS (400s if requests don’t conform, 500s if responses don’t conform).

At a previous workplace I’ve used OpenAPI Generator to generate clients and server stubs from the OAS, which is a nice approach to ensuring you’re confirming to the spec, too.

[lolive]

Did you have the requirements for users that you do not know want to define their own API upon your data?

[yashap]

No, it’s never come up. This is touted as a selling point of GraphQL, but IMO is mostly solving a problem that few people have. Having worked a lot both consuming and producing external APIs, people seem happiest with idiomatic, well documented RESTful APIs, they don’t want to learn some complex RPC system like GraphQL just to use your API.

I think these GQL benefits are somewhat legit:

1. Fetch in one round trip what would take multiple with REST

2. Fetch only the response fields you need

But honestly, 1 generally saves 0-1 round trips, and for 2, while response payloads are smaller, GQL requests payloads tend to be huge, so it’s largely a wash. At least in my GQL usage, they’ve been minor wins, not worth the complexity that GQL adds.