Standalone, generic version?

[gabesullice]

Hi!

I just became aware of this project this morning when a contributor to the Drupal project linked to this project because they wanted to use it with Drupal's JSON:API implementation.

It looks very cool and is almost exactly the thing I've been dreaming of creating myself. I love it when this happens :D

I'm wondering if you'd have any interest in making the VueJS app capable of working with any JSON:API backend. In the past, the blocker to this was probably that areas of the spec like filters and meta members made each implementation too different. However, version 1.1 of the JSON:API spec introduces the concept of profiles, which can be used to communicate (and standardize) differences between implementations (like a filtering syntax).

Finally, the JSON:API editors are looking for uses of profiles of the wild and this would be a great way to validate them so we can make 1.1 official.

Thanks!

Gabe

[richmolj]

Hey @gabesullice! Thanks for the kind words ❤️

I support a generic JSON:API backend in theory, but I'm not quite sure how you'd get there without a schema. We wouldn't know which fields were filterable, or what operators each field supports (suffix, prefix, greater than, etc).

I can imagine a world where we support alternate filter/etc syntax, but the schema seems the real blocker to me. What were you thinking there?

[gabesullice]

@richmolj, for Drupal's purposes, we already have a way to generate a JSON-Schema compliant schema document. Is that the format you already use or does Vandal use something else?

I do agree that to be truly generic we'd need schema support at the spec level. The good news is that schema support is something that I know all the spec editors are very enthusiastic about supporting. The bad news is that the spec doesn't move very fast.

That said, we could author a schema profile today in order to jump ahead of the base spec and then wait for it to catch up.

[richmolj]

We use a different format, though there's some possibility for overlap. To dive a little deeper:

The biggest issue is most "REST schemas" (e.g. swagger) detail a request, response, parameters, and so forth. Makes sense, but not with a "Graph API" - if you can query nested levels of the graph from a given endpoint, you end up with an explosion of parameters and duplication. When this project was JSONAPI Suite, we had a Swagger UI that suffered for this reason.

The solution was to instead lean on the JSON:API specification itself for things like request/response, and instead our schema details the Resources. After all, the premise of Graphiti is to define your Resources and use that information to satisfy any specification (in theory). That's one of the reasons we can render flat JSON in addition to JSON:API, and why a sister experimental project renders GraphQL. Here's the schema from our sample app. Verbose, but simple.

But even if you didn't render that exact schema, we just need a way to pull data and build-up Resource constructs, detailing the filters, types, fields, relationships, etc. Then specify which endpoints expose which Resources. That would give Vandal enough information to render the forms, and we could have some pluggable way to adjust the URL as well.

So, that's the long answer and why this might be a heavier lift. We're detailing Resources instead of a Request/Response, so any alternate schema would have to detail the same (or at least go through some processing code to detail the same in JS memory). I absolutely believe this is the correct way to go about it, but may make the lift here somewhat high. I can definitely provide some guidance if it's a direction you'd like to pursue more, though.

[gabesullice]

@richmolj, I hear you! JSON-Schema != OpenAPI (Swagger). I'm not a fan of the OpenAPI specification either. I do not appreciate that it dictates that you must specify your endpoints. IMO, a schema should only define data types, never URLs. IOW, it should define the data not the API. And that's what we can do with JSON-Schema.

I think the biggest challenge will be figuring out how to communicate which fields are sortable and filterable like you've done in your schema. I think it can be done though. Maybe through the metadata of JSON-Schema.

Thanks for all your help and your offer to provide some guidance. I'll be working with @shaundrong over the next few weeks to explore this further. Maybe as a proof of concept, we'll just map our schema into your format.

[richmolj]

Awesome! Sounds great. It wasn't quite what I was looking for at the time, but I'm interested in supporting JSON-Schema as best we can. If you have something compatible, we might even be able to generate a JSON-Schema from Graphiti with a configuration flag.

Good luck! ❤️