GraphQL PIM API
Crystallize are delivering structured products and content via our API. For our API we have chosen to use GraphQL. GraphQL allows you to select exactly what data you want to have transferred resulting in smaller payloads and a more responsive API.
Easily fetch only the data we need
The number of calls to the back-end API is a super-important point when designing highly performant frontend architectures. If you are being truly RESTful you have one query for a list of resources and then one prefetch request in addition to the query for fetching data for each resource. Ten resources would result in 11 REST calls, 22 if you count the prefetch requests, minimum. With GraphQL you can fetch a complex structure of information and even have multiple queries in one call. This results in one API call when GraphQL is done well. A game changer compared to REST.
Since GraphQL can fetch complex data structures at once you can recognize common patterns. These patterns you can optimize for on the server side. For example fetching all products and recommended up-sell products for each in one product category - in one call. Fast.
Developer Experience with Magic Input Validation
We get guaranteed input validation coherence with GraphQL schemas. The GraphQL library will handle the input validation based on your GraphQL schemas. Ensuring that every query fired off to your server is following the schema. So long as you trust the library implementation. Apollo works great for this so far. End to end coherence. Sweet.
With REST we had to manage input validation ourselves. We used JSON Schemas also for testing and had to manually make sure they were matching our actual API code. Double work, boring and error prone. This issue vanished with GraphQL.
We still have to perform logic validation like length of strings or range of numbers, but the main structures of our input data is validated automagically. This enhances code quality while keeping developers calm. No more Open API documentation in beautiful Yaml syntax. Yay.
Developer Experience with Self Describing API
Outdated API documentation sucks. With GraphQL we automatically have the details of our API being generated according to our schema. The GraphQL playground allows developers easily to discover the capabilities of the API with autocomplete and schema search. The learning curve for the API is reduced.
Documentation writing requires much less work. GraphQL guarantees that the specifics of the API are automatically documented, so you can focus on writing concept based documentation with a few examples. For us meaning: covering concepts like what is a shape and how it is used.
