• Schema overview
  • GraphQL API
  • For Developers

    • Overview of the schema

    In this article:

      Attention   

       

      Introduction

      To improve your understanding of the GraphQL API, there are some things you should further familiarize yourself with.

      We have two publicly available schemas: public and experimental.

      The public schema is where you will find our stable public API. This schema will *never* experience backwards-incompatible changes outside of our major releases. We will provide a timeline before any upcoming major release, and anything subject to removal will always be marked as "Deprecated".

      The experimental schema is where you will find our bleeding-edge API, which closely mirrors what we use internally to power the new administration. This API, importantly, SHOULD NOT be considered stable, and may frequently experience breaking changes. As such, you are advised to use this schema at your own discretion.

      We welcome feedback for both schemas. Note, though, that any proposed changes to the public schema are much less likely to take effect, than suggestions for changes to the experimental schema.

      Therefore, we encourage developers to always keep an eye on our experimental schema to get a sneak-peak at potential upcoming changes to the public API, which will always be available in the experimental schema first. Doing so not only provides you with insight into the possible future state of the public schema, but also allows you to provide valuable early feedback.

       

      Disclaimer:

      Due to limitations of the API gateway we are currently using, some features of the official GraphQL specification are not supported.

      In particular, this includes (but may not be limited to):

      • Auto-wrapping of single elements when provided where a list is expected, e.g. providing "foo" when [String] is expected.

       

      These issues are being looked at, and will be patched in the future.

      Versioning

      The GraphQL API uses semantic versioning as its versioning paradigm.

      Semantic versioning prescribes version numbers of the form <major>.<minor>.<patch>, e.g. 1.12.34. Whenever backwards-incompatible changes are introduced, the major version MUST be increased. Thus, if we rename or remove a field from a type, query or mutation, this triggers a major version bump. This is something we will attempt to do sparingly, in order to increase the longevity of the API as well as providing a better experience for API clients. Adding or deprecating fields will trigger a minor version bump. If we change the description or sorting of fields or types, or if backwards-compatible bugfixes are performed, we will increment the patch version.

       

      NOTE FOR BETA:

      While the API is in beta version, meaning we are actively developing it, we will be using major version 0. For the purposes of our versioning, this means that we will increment the minor version in the case of backwards-incompatible changes (not the major version).

       

      General structure

      Currently, our queries and mutations take on several different forms, but the `public` schema reflects how we intend the schema to look going forwards. This section outlines that structure.

      All queries and mutations take the form:

          
    mutation entityAction(input: EntityActionInput): EntityActionPayload!
    
          
    query someQuery(input: SomeQueryInput): SomeQueryPayload!
    query otherQuery(): OtherQueryPayload!

      This provides a uniform structure for all GraphQL requests and responses. The return type of a query/mutation, e.g. `PageCreatePayload`, contains the result of the request, as well as any errors that occurred as a result of invalid user input.

      Continuing with the previous example, this is the structure of the `PageCreatePayload` return type:

          
    type PageCreatePayload {
        content: Page
        errors: [PageTreeClientError!]!
    }

      General principles

      There are a number of conventions that we use throughout the API:

      • Types are always named using upper camel case, e.g. OrderLine.
      • Queries and mutations are always named using camel case, e.g. orders.
      • Mutations are always named such that the entity, which the mutation affects, is listed first, followed by the type of action performed. E.g. orderCreate.
      • Constants (valid entries in an enumeration) mostly use names capitalized with underscores, e.g. GREATER_THAN, an instance of SearchComparator.
        • Note: The only exception to this are types, which enumerate fields on another type. An example is this would be the elements of the OrderSearchInputField enumeration.