Specification

This document adheres to RFC2119

General

  • the API must be a GraphQL API as specified

  • entrypoint must be /graphql/

  • default HTTP status code must be 200

  • use OXID models and create DataTypes as facades for GraphQLite

  • when the object queried does not exist, the API must respond with a 404 HTTP status code

  • when the object exists, but is not accessible for the current user (oxactive set to 0, oxhidden set to 1 or other reasons), the API must respond with a 401 HTTP status code

  • when an inaccessible or non existing object is requested via a relation from another existing object it must be ignored, the resolver needs to return null in that case

Login/Auth

  • auth against the API must be done via a Bearer JWT in the Authorization HTTP header

  • the token query must not have a token sent with the HTTP request

Naming

Queries

  • must not have get or has or similar prefix

  • query name must be singular or plural object name

  • valid examples:
    • user

    • users

    • product

    • products

  • invalid examples
    • getUser

    • fetchProduct

  • must have proper input type definitions

Queries for lists

Additional to the rules applied for the queries, when querying for lists the query should have the following input parameters - all optional.

  • filter which should be of type ObjectFilterInput (which you have to create and name accordingly)

    • the fields of this FilterInput type should be of one of the provided filter input types

  • sort which should be of type ObjectSorting (which you have to create and name accordingly)

  • limit which must be of type Int (if ommitted must behave as no limit)

  • offset which must be of type Int (if ommitted must behave as 0)

Mutations

  • must start with the object name, then the action verb (camelCase)

  • valid examples
    • userRegister

    • categoryCreate

    • categoryUpdate

    • categoryDelete

  • invalid
    • createuser

  • should not use generics (create, update, delete), but the correct domain verbs where possible (register user vs. create / add, place order vs. create, …)

  • must have proper input type definitions

Fields

  • every field from every model should be available as a GraphQL field and must have a correct type annotation (ID for oxid database field, not String)

  • multilanguage fields must not be exposed separately, but in context of the language of the token as a normal field (no title_1 or title_2 fields, only title for the oxarticles.oxtitle\* database fields)

  • parent ids, object ids, foreign keys (relations), etc. must be exposed via their correct type

    • example: a product has an oxvendorid, which should not be exposed as ID or String field, but as a relation to that specific type

    • you may additionally add the field with the ID type when necessary

type Product {
    # do
    category: Category!
    # don't
    categoryId: ID!
}