[sbacic]

I'm currently working on a full-stack app centered around GraphQL and my experience is pretty similar to yours - when it works, it's like magic. The problem is, it doesn't always work the way you expect it to. Here are some of the things I've noticed:

While the main technologies are pretty mature and well documented, gluing them together is often a lot trickier and left entirely to the user. If you need a way for Apollo to communicate with the database, you have to handle that yourself. Same thing for authentication and access control. File uploads also require a separate library.

I think the whole stack has a lot of promise, but it's going to have trouble gaining steam as long as it forces the user to think about these sort of things.

Something else I've noticed is that it shifts a lot of the work to the back-end while at the same time introducing new problems you never had with REST. With REST, you had endpoints with clearly defined inputs and outputs, which were easy to reason about and secure. This is not the case with GraphQL - because it is so expressive, it's hard to cover every possible use case, especially if you're doing the entire security and access control yourself. The other problem GraphQL has that REST does not is recursive queries - it's entirely possible to request something like this:

authors -> posts -> comments -> authors -> posts -> comments ...

Another thing I should mention - while Prisma and Apollo are pretty stable and well documented, various smaller libraries are often not. This is not an issue specific to GraphQL, but because it has a smaller ecosystem then say, React, you're a lot more likely to run into it.

Lastly - the pace of the development is bonkers. I've run into situations where an 8 month old post was already obsolete. Or major versions a year and a half apart.

[bsbechtel]

I lot of the issues you mentioned really are meant to address problems faced by teams working on a project at scale. I really didn't understand the need for GraphQL until I was put on a project where we had multiple REST endpoints we needed to query data from, new people were joining every week, and communication + data requests across different teams required a significant portion of everyone's time.

The issues you mentioned are issues if you want one (or a few) framework or library to handle all of your web development needs, but rarely does one library work for web development at scale.

[sbacic]

It sounds like your issue was with poor documentation and not some fault inherent to REST itself. I don't think that just switching to GraphQL is going to fix that problem (though Playground is a pretty nice way of getting to know the API).

I guess my main qualm was that, because GraphQL does a relatively poor job of explaining why you should use it, people like me get the wrong idea about what kind of problems it solves and why you should use it instead of REST.

[bsbechtel]

It's not really an issue with documentation within our team. It's an issue of having hundreds of REST endpoints (all which need to be learned by new devs), multiple local dev servers running on your machine to mimic those endpoints, and an excess of work done on the front end to merge data from across those REST endpoints once it all arrives on the client. Additionally we would get requests from other teams wanting to access data, so instead of them just writing a query to the same GQL endpoint we all share, we have to write a new endpoint for them, manage access control on that endpoint, etc. These are the issues GQL solves.