It’s a well known fact that the problems GraphQL seeks to solve in REST/OpenAPI are not actually very well solved (if solved at all). The main problem being, idiomatic RESTful OpenAPIs facilitate CRUD only on resources/entities (e.g. given by an ID or an array of IDs), which is quite restrictive given the APIs rest ontop of a database that has full querying capabilities.
GraphQL does not solve this. It just sounds like it does because it has “QL” in the name, but it doesn’t. There is also no reason at all for it to have its own custom querying language instead of being built ontop of REST data-formats (again, other than the fact that it has “QL” in the name)… or just being a REST API altogether, with added conventions for querying… I digress though. You can just hop on YCombinator’s HackerNews and see what the most competent developers think about GraphQL.
I just want you guys to know that building and developing with this “GraphQL API” is in no way shape or form simpler than dealing with a REST API that simply has a querying language or grammar (of which I’ve written several of these myself that are used in production environments just fine… they are self describing and self explanitory and other devs rarely ask me how to use them)
On the flip side, I have not been able to craft a single query on my own for the API without starting from an example copied and pasted from somewhere. Also your API doesn’t support bulk/batched GraphQL requests.
RESTful OpenAPIs are self explanitory. I have never dealt with a GraphQL API before ShipHero, but I guarantee you (And you all know full and well) there is nothing self-explanitory about this API.
As an example, the Schema features a “Warehouse” model, however you cannot actually query “warehouses”, to query warehouses you’d have to do this: Get all warehouses - #2 by tomasw
Yes, that’s super self explanitory. You first must query “accounts” and then add warehouses to your projections… Duh! Of course you wouldn’t just craft a query for warehouses themselves.
Another nuisance is the insistence on branding the data model with “graph-like” properties… I guess to make it more “Graph-y” like? Putting the Graph in GraphQL? I don’t know. But providing me an array called “edges” that are filled with “nodes” which then actually contain the data I want instead of just providing an array of the data I want is the most annoying thing I’ve ever seen intentionally done in an API for no reason whatsoever.
This does nothing but make the data objects look more complex which increases the learning curve for lower level developers attempting to use API endpoints I write which return data passed through from your GraphQL API…
Whatever developer/engineer is responsible for this decision should never be given the freedom to design systems on their own (at least not for a salary). They clearly will just do whatever buzz-wordy thing they see on the top of a Google search with zero reflection on the original problem they set out to solve. Regardless of the fact that it makes life more complicated not just internally, but externally for customers as well.
No developer is innocent of overengineering a component or two from time to time, but to write an entire API where the basis for development in the first place was overengineered is crazy. I think the closest I’ve come to something like this is opting for Kubernetes over AppEngine thinking it would cut costs… it didn’t, but the transition back to AppEngine was painless, no harm no foul. What’s your transition away from this GraphQL API going to look like I wonder? Countless months of project planning and implementation I presume?
I hope you are expeditiously working on a replacement to the GraphQL API (and the developer who set it up), because if not, the typical pattern of behaviour you’re going to see with customers that do technological integrations is that they end up building their own internal logistics system and foregoing ShipHero altogether (Something I have already convinced my boss to put on our Roadmap)
And when we make that internal logistics system, please believe we intend to compete, because you guys have made it so easy.
I am almost positive at least half your customers with technological integrations would absolutely eat up an alternative shipping and logistics API… the biggest value added by you guys is that you handle tracking labels for various carriers and from the planning I’ve done for our own internal logistics API, that is the bulk of the work; sorting out integrations to all different carriers and properly printing tickets/labels for parcels to be delivered by them, the rest of it is just storing the data in a model that actually makes sense and exposing it via an API that’s actually self explanitory, rather than shoe-horning it into GraphQL and assuming it will solve the problem of creating a customer-friendly API.
Also, ironically, this is not even something you can do via the GraphQL API… we still must go into the ShipHero app and manually print labels. My guess is that you guys are fully aware that is where your actual value is and if you exposed an API to print those labels, you’d be in competitive trouble.
I am not sure what the state of the legacy REST API was, or how poorly it must have been designed for this to be considered an “upgrade”, but again, I have literally built REST APIs that act as Data Access Layers over ORMs for several different kinds of databases (both SQL and NoSQL). This is a joke and the most frustrating experience I’ve ever had for an API whose only responsiblity is to provide web access to data…
Tl;Dr: GraphQL was a super poor decision, and if it’s not dealt with in the near future another logistics API will usurp your customer base. I will focus on targeting ShipHero customers with technical integrations.