GraphQL PIM API
Crystallize delivers structured products and content via our APIs. For our APIs, 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.
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 can be optimized for on the server side. For example, fetching all products and recommended upsell products for each product category, in one call. Fast.
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. Apollo works great for this so far. End-to-end coherence. Sweet.
With REST, you have to manage input validation yourself. We used JSON schemas also for testing and had to make sure they were matching our actual API code manually. Twice the work, boring, and error-prone. This issue vanished with GraphQL.
You still have to perform logic validation, like the length of strings or range of numbers, but the main structures of your input data are validated automagically. This enhances code quality while keeping developers calm. No more Open API documentation in beautiful Yaml syntax. Yay.
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 to easily 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. (Such as covering concepts like what is a shape and how it is used.)