The story of the GraphQL API for OXID eShop

When I started my journey with OXID eSales in mid of September 2019 my mission was set to build a GraphQL API for the OXID eShop. So I started with checking out what we got, here is the list:

  • GraphQL Base Module
  • very few people in house that had worked on this
  • a project from professional services that already used what we had

Talking to everyone who participated in building the oxid-esales/graphql-base module, used it in a project and checking what is the state of the art when doing GraphQL with PHP was time-consuming, but in the end we decided to refactor the GraphQL Base Module to ramp up developer experience and use state of the art tooling.

So to get the team on board and get the work on the GraphQL API kickstarted, we decided to meet in person where the majority of us works and this came out to be Plovdiv, Bulgaria. As the remote team had grown immensely in 2019 and some developers had not yet met in person, it was not only for me to meet all the fine people on the team for the first time.

Everyone you see in this video is involved in developing the GraphQL modules for OXID eShop and this is the current state:

GraphQL Base Module

We decided to base our work on GraphQLite. It is a PHP library that allows us to write GraphQL queries in simple-to-write controllers. All there needs to be done is to use PHPDoc annotations and GraphQLite creates a GraphQL API for you miraculously. Just like magic!

This allows us to go fast and use state of the art tooling, e.g. static code analysis powered by PHPStan. GraphQLite itself is based on webonyx/graphql-php, the de-facto standard PHP implementation of the GraphQL spec.

All in all, we have prepared the GraphQL Base Module for OXID eShop to do a few things for you

  • it brings as a dependency and bootstraps GraphQLite v3
  • brings the first query – a token query, to provide you with a JWT for authorization
  • it gives you the base for extending and creating your queries, mutations, and types with your modules easily
  • helps you in writing integration tests by providing an abstract TestCase

GraphQL Example Module

The GraphQL Example Module just serves one purpose: give an example on how to build your own queries, mutations and data types. We are going to ditch it, you will understand later why we plan to do so

GraphQL Module Skeleton

The purpose of this module skeleton is to serve you with a starting point when building your own GraphQL API or extending the existing one. Basically all you need to get started is:

$ composer create-project oxid-esales/graphql-module-skeleton

GraphQL Catalogue Module

This is what the remote team is spending the most time on. If you have followed the OXID eSales namespace on GitHub, there is nothing that should be surprising, but here comes the news.

This module brings queries and data types that you need in order to build a frontend by only utilizing the GraphQL API, from start page over categories and manufacturers to product detail pages and reviews. Up until now, this was developed in a private repository on GitHub, but starting today:

  • this repository is public and
  • licensed under the terms of the GNU General Public License v3.0

This also makes you understand why we are ditching the example module, there is no better example than the implementation itself.

So go ahead, check out the module on GitHub and feel free to ask questions and contribute!

Next up …

Our current plans for GraphQL are

  • tag the catalogue module release when all the functionality for building the catalogue view with GraphQL API will be available
  • build an account module that supports the frontend user in everything he can do (besides checkout)
  • build a checkout module that supports the complete checkout funnel
  • build an admin module to be able to control every aspect of the OXID eShop via the GraphQL API