We're starting to build API endpoints with this where I work. We didn't have compound documents in an earlier version of our API, and we ended up having to make a lot of roundtrips for some things. So I had been thinking about something like the jsonapi "include" mechanism, and when I saw how jsonapi was doing it, it was pretty close to what I would have done. That made me feel better about going along with their decisions in areas I haven't thought about.

They keep saying that they're closing in on 1.0, but there's a few issues left:

https://github.com/json-api/json-api/issues?q=is%3Aopen+is%3...

They've been making a lot of changes lately:

https://github.com/json-api/json-api/graphs/contributors

It's good that they want to get all of the breaking changes done so that they can declare a stable 1.0. But it also seems like they're going to try and call it stable right after making a bunch of changes, which seems risky.

I also pitched JSON-LD/Hydra at work, because they're w3c-backed and JSON-LD has some uptake. But the other people who looked at those specs found them hard to digest. And I agree; as an implementer, I can read the jsonapi docs quickly and have a pretty clear idea of what to do. But with JSON-LD/Hydra, not so much.

I get the sense that JSON-LD/Hydra is more flexible than jsonapi, but I think jsonapi does what we need. And if it does what we need, then additional flexibility might actually be a drawback. I guess we'll see how it goes.