Hello All,
Just came accross the JSON:API specification, reading about it. I can’t find information how does it relate to API-definition specifications: Swagger, RAML, API Blueprint. At first sight, JSON:API and these 3 solve similar purpose: they define API contract to be conformed to by both Frontend and Backend. This enables auto-tools such as docs generators, stub server generators, API-test generators, etc. And these 3 are proud of their stack tools, e.g. see Tooling in https://apiblueprint.org/.
So, mainly, my question is: is JSON:API another alternative to {swagger, RAML, API Blueprint}? If not really, what is its purpose? What is its advantage over these 3? I know it’s a specification for defining APIs. But so are above 3 mentioned.
No hate here, not at all. Just asking. Maybe JSON:API has something interesting I don’t know about.
Hi,
So, JSON API has slightly different (but complementary) goals from the documentation tools you mentioned, and it can be used in combination with them.
Basically, JSON API’s goal is to impose a common structure on APIs (e.g. to say “all APIs that support including related resources should do it this way”). This helps API authors by offering them well-thought-out patterns for supporting common features, so they don’t have to reinvent the wheel. And, it helps API users by making their knowledge more transferable. (If a developer’s used one JSON:API API, they already know a lot about how to use another, even without looking at its docs.)
Also, JSON API allows for client developers to use existing libraries to consume the API. This is similar to how Swagger et al can generate a client library for a given API based on its documentation—though with a JSON:API API the API author has to do less work upfront documenting things, and the resulting client will have a more predictable (and perhaps better tailored) interface, since the only thing that varies from one JSON:API API to the other are the models (for the most part).
A JSON:API API can still be documented with Swagger et al, for people who want the benefits of those formats, or it can be documented more simply, just by describing what’s unique about it and referring people to the JSON API specification for the rest.
Finally, there may be certain semantics that a JSON:API API expresses that can’t be communicated with Swagger et al to machines. For instance, when a JSON API error occurs, a generic client can know exactly what each field in the error object means (since those meanings are defined by the spec), and can provide default handling behavior. My understanding of Swagger et al, by contrast, is that it’s certainly possible to say “the error response’s JSON will have this shape”, but it’s not possible to express the semantics of each field in a machine readable way. And the same goes for other semantic bits in the JSON API spec, like the values of the "links" key, each of which has a predefined, machine-knowable meaning.
3 Likes
I have similar comments to @ethanresnick. Swagger, RAML, and such are a description language. They’re a way of taking an API and describing it in a way machines understand. There’s no consistency or similarity required between any of these APIs, but you do get shared tooling.
JSON API is about creating shared tooling through shared conventions. This gives rise to things like
I created an example jsonapi swagger :
http://thomaxxl.pythonanywhere.com/api/
Using code from https://github.com/thomaxxl/safrs
Not all jsonapi is implemented but the schema validates.