What's the name of this thing? (and how to promote it without confusing people?)

#1

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?

1 Like
#2

JSON:API is literally the first result when you search these keywords.

Have you tried saying “let’s implement the JSON:API standard on the JSON messages we exchange? That way we could build a RESTful solution with all the advantages of hypermedia links, for instance.”

I believe that people give you much more credit when you explain which problems your solution will tackle.

1 Like
#3

Yes json:api is not good at promoting itself. The common mental model of a developer of an API is not HATEOAS nor RFC 5023 - The Atom Publishing Protocol but maybe something more like custom JSON with beautiful URLs. You cannot update this mental model in a flash. json:api was made by HATEOAS influencers. If you are lucky enough you understand where it comes from and that it is deeply rooted in the Web. But the project influencers at your job may certainly understand why a protocol, a predictable way to discover and interact with your domain objects as a graph are beneficial constraints on the long run.

Whatever the name of the protocol/format, json:api is quite deep and subtle. If you understand why it may be beneficial for you project, you have an opportunity to bring some knowledge by presenting it to your project influencers.

1 Like