Consider compatibility with jsonapi.org? about http-api-design

[ms-ati]

All: please try to restrain yourselves from the xkcd multiple competing standards links.

[geemus]

Both the design outlined in this guide and in jsonapi have similar goals, but we disagree on some specifics. I think we do complement one another in exploring the same problem space and we certainly do agree on a number of points, but I'm not sure how we can improve compatibility around those places in which we disagree. That said, I'm also not sure I entirely understand what you envision in terms of an ideal future. In an ideal world, what do you imagine compatibility would look like?

[ms-ati]

Good question. In an ideal world?

Perhaps there are some specifics that differ for no good reason, and these can be unified after discussion. Perhaps there are other specifics that may differ due to actually different goals, and these differences in goals can be examined and explained.

Ultimately, I think in the web development community we'd like to pick one standard, and design libraries which adhere to the standard. That's my interest, at least, for starting the conversation about this.

Alternatively, competition can drive excellence. Perhaps both projects can market why they think their individual differences are better. But again, that requires being aware of and minutely examining the differences.

Does that make sense?

[geemus]

Yeah, I think so. Thanks for taking the time to dig in, I wanted to try and speak to your particular concerns rather than just glazing over things.

In my view one of the biggest differences is about where to communicate the shape of the API. We do it using schemas, which are out-of-band. So you fetch a schema to see what links are available, how to do various operations, what attributes are valid etc. jsonapi instead passes this and a lot of related information over the wire with things like links envelopes. I think that these sorts of things should remain relatively stable and be cacheable (which can be done via headers with a schema, but not so much with links that come back with all requests). I think that is probably the most fundamental difference, but I suspect it informs many of the smaller differences that bubble up around the edges.

We have chosen json-schema as the standard to base our schema upon and have seen others also move toward this (ie https://github.com/pandastrike/jsck). Similarly we have seen others in the space, like swagger and blueprint, starting to adopt more json-schema usage in their tooling. I think this does offer some of what you hope for, namely that there are a few projects working on different edges but with more of a shared core. Unfortunately jsonapi does not provide a json-schema and indicates that they don't believe json-schema can fully represent their design, so they are not really able to participate in this part of things.

So, we hope at least to be moving toward the sort of ideal you mention, but maybe not in quite the same part of the ecosystem as jsonapi is. Does that help/make sense?

[ms-ati]

Thank you that is very helpful. So much so, that I was wondering if it might make sense to capture this text, or a variation of it, in a document that is part of what you publish. Maybe a FAQ "How does this project differ from jsonapi.org?", or such?

[geemus]

Quite possibly. I have a few revisions I hope to undertake, but seem never to quite get to. In the mean time I'll certainly leave the issue here for others to find and hopefully I'll find a good home for it in a future revision. Thanks for asking about it and certainly let me know if you have further questions or concerns.

[oliverbarnes]

Not sure if this is a new development, but jsonapi does have a schema now, fwiw

[geemus]

Cool, thanks for the heads up!