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!
}