At Unite 2021, we announced that we want to make some changes to the Storefront GraphQL API that historically haven't fit well within our versioning system. These changes come in various forms from cosmetic to functional, but overall we want to improve the Storefront GraphQL API's schema to be more easily understood and used by you, the developer.

Below you will find details on what changes we are proposing and why, but the most important thing is we want your feedback:

• Do these changes make your job easier?
• What is missing that you desperately need?

Why are you doing this?

Over the years, the Storefront API has grown to support many new features and use cases. The majority of these improvements are purely additive and are not considered a "breaking" change. However, there have been times where in order to support new features we have had to resort to some less-than-desirable techniques to keep in line with GraphQL's best practice of evolving, not breaking. Some examples of these are:

• The introduction of version-suffixes on types and fields, such as MoneyV2 or priceV2.
• Deprecating fields but never actually removing them to avoid breaking apps who can't update.

These types of changes over time have resulted in a schema that is hard to understand by developers, and from our point of view difficult to maintain in the long run.

What is changing?

At some point in the near future, we will be releasing a new and improved Storefront GraphQL API schema. The goal with this new schema is to have a fresh start and solid foundation to grow on, built against new principles that will help prevent getting into this situation again. To be clear, this schema will have many breaking changes from the release before it, and that is the point.

Some of the higher level changes include:

• Any fields or types that have a version suffix will be renamed to remove said suffix.
  • MoneyV2 => Money, Article.authorV2 => Article.author, etc
• Any fields or types that have been deprecated in a previous release will be removed.
  • As a general rule going forward, a field or type that is deprecated in a release will be removed in the subsequent release.
  • For example, a field deprecated in 2020-07 will be removed in 2020-10. Remember that 2020-07 will still be available for one year after its initial release.
• Moving away from multiple similar field names in favor of simple arguments or reusable object types.
  • Example #1: Query.productByHandle becomes Query.product(by:)
  • Example #2: Product.description: String and Product.descriptionHtml: HTML become Product.description: RichText.
• Fields that return similar values will be named the same and be defined within reusable interface types where possible.
  • For example, Page.url, Article.url, and Product.onlineStoreUrl all become OnlineStorePublishable.onlineStoreUrl.

A more detailed list of changes is available here.

How can I play with the new schema?

In order to help you get to know the changes, we have put together a mock GraphiQL playground where you can make read-only queries against a fake storefront. However, there are a few key things to be aware of:

• It is read-only, therefore mutations are not available.
• The data returned from queries is mocked - that is to say it is randomly generated and may not make the most sense.
• As we iterate on the schema based on feedback, the data returned may change over time.
• The playground doesn't currently include the entire scope of the Storefront API. For example, the new cart functionality has been omitted as we would encourage to jump into this discussion for specific feedback on the cart.

Looking forward to your feedback. Please comment below. 👇