Just discovered this https://jsonapi.org/format/#document-top-level - anyone used it and have opinions?

That's useful, thank you for sharing this.

just starting to explore it myself so can't say good or bad yet but nice to have some kind of standard!

I have consumed an API that I think may conformed to that standard. It definitely creates odd objects when you start getting complicated systems. I never saw the "standard" written so it was always guess or check for us.

We looked into it a while back and there were a couple big discussions of it here. My takeaway was that you need to have standardization have a whole lot of value in your project, e.g. multiple stakeholders and lots of complex data, because otherwise it's over-engineered

4.2 and 4.1 are red flags to me. Using non standard content-types is a bit sus for me.

We started off with the intention of doing REST but quickly hit limits with it and now have a ball-of-mud. GraphQL isn't an option in CFML land so this looked promising. Seems it's part of Drupal for what that's worth.

We use a modified version of the Ortus generic API response object, which is way simpler than anything JSONAPI is trying to do. It starts turning into a ball of mud when we get resources that are combinations of things -- for instance, we do youth sports, and we have a 'player' (a person with a name/dob/gender/etc) and we have 'a registration' (that player's presence in a particular season of play) and nine times out of ten, somebody wants a combination of both of those things. We've "solved" this in some cases by using fancy combinations of schemas with the OpenAPI spec where we can do unions or intersections of different files but it very much falls on the 'powerful but disorganized' side of the spectrum. We can do whatever we want without many constraints but we do sometimes solve the same thing three different ways because no one person has a super great view of the whole API. But...that's also an honest reflection of the business. 🙂

Thanks - appreciate your thoughts / experience

Yeah, it's trying to slay way fewer dragons than JSONAPI

I was recently looking into the whole GraphQL thing and wondered why GraphQL isn’t an option in cfml as @aliaspooryorik points out - is it a technical limitation of cfml or just not enough people in cfml to get something up and running? Is there a java graphql engine that could be proxied?

I thought Eric at Ortus had a module for GraphQL but maybe it was just a prototype. I know he played with it a bit but don't see anything on Forgebox

Eric has a module for everything - even making Pizza

I currently use taffy which is great but end up with lots of REST endpoints. I originally started building a version of our API using jsonapi but it quickly became bloated and more complicated than I felt it needed to be.

I use ColdBox for my APIs and love it because it is versatile, and depending on how you want to structure your endpoints, it can cut down a ton on endpoints by grouping related data. It works for simple and complex APIs, versioning by modules. So, it is easier for me to understand one framework that can handle complexities, but I can still just as easily create a simple API with it as well.

We're using Taffy as the framework but the response is based on the jsonapi spec, although not strictly. One of the things I like is being able to include related data which would otherwise require multiple requests

"graphQL isn't an option" doesn't make sense to me. It is just a different client api to your internal workings. You could use the java libraries if you needed to. The question comes down to who is consuming your data and why you want it to be sparkly clean? If you are just doing internal apis then just use your own standard and make your own contracts. If you are creating and selling an api, then using a spec makes sense. It all comes down to how much work you want to put into it and 90% of the time internal api don't need that much thought.

It's an internal API - but it's a wild-west currently (the oldest code is "remote" methods)! If I can find some kind of vaguely sensible spec then I can just say "do this" and not get bogged down in the personal preferences of each developer (same goes for code formatting so just saying "ortus cfformat rules" ends the internal bickering!)

Yea we have a siimple spec of get requests with lists comback as an object with the key of the items you pulled, and everything else comes back as the struct it has. Error reporting/handling is done via the headers/statuscodes.

I feel very much like the sheriff who has been assigned to the wild-west where the last sheriff "disappeared" at times with this code base 🙂

Ha I feel you there. I have been in that position very often and have lost that batter a lot. If you can't get all the devs to agree on one small thing, it just won't happen.

ha - I know what you mean. I'm thinking more of making it easier to onboard "devs of the future"

Hmmmm is that really where you have your sore spot in onboard, the return format of api calls?

No, but being consistent in the code we have is not a bad thing to aim for.

I mean true, but then your going again back to pushing an idea on existing devs for a reason that has little gain for a potential future dev.

I'm not planning on enforcing it for existing endpoints that already work. Sure when we rebuild them in React (or whatever) then I'd like to be consistent in the server response. I'm actually picking up on a piece of work that someone else who has left started so it's not in production yet. I'm taking the opportunity to review it before it goes live and will then be stuck like that for the next 10 years.

I think I like the ‘idea’ of graphql to able to request just a small subset of data fields for a list of say organisations, e.g. organisation name and address from the same endpoint that could also give me all of the data for each organisation - which would be a much heavier data object. At the moment I have 2 options, provide a filter arg to show a fixed subset of data or the whole lot or create multiple endpoints for each permutation. But I fear there is less work in those options than building a graphql solution from scratch in cfml - maybe a node option will be something for the future, I’m not quite there in the node learning curve.

If you want to experiment with graphQL and what it can do the best strategy to start with is standing up and looking into apollo. It is something that can be put in front of a rest API as well as other servers, receive the graphQL request, parse it out to each appropriate server behind the scenes and then return a proper response. Obviously not as easy as a 2 sentence statement but it isn't to bad.

Apollo might just be the ticket - looks good!