I really like this spec and the idea of there being a standard but I find it really hard to promote. This is the usual conversation:
Me: “I think we should use JSON API”
OP: “Yeah, we’re using JSON for our API” (wondering why my grammar is so bad for a native English speaker),
Me: “No, I mean we should conform to the JSON API spec”,
OP: “It does - it’s run through a JSON validator in CI”
Me: “No, I don’t mean the JSON spec, I mean the JSON API spec”
OP: “Oh, you mean we should make a JSON Schema and validate it with that. Yes, we already have a JSON schema that we validate against in CI”
Me: “No, that’s not what I mean at all”
OP (thinking I’m crazy): “Ok, let’s wrap this meeting up now… thanks for your input, but us backenders have got this one” (regrets inviting me to the API design meeting, files a note for next performance review “does not productively contribute to meetings, just tries to sound smart, but clearly has no idea what he’s talking about”)
Perhaps OP searches “JSON API” and gets a random bunch of results to do with json APIs in general which just confirms his suspicion that I’m crazy.
Have you ever thought about giving it a less confusing name?