ActiveQL concepts

We believe - as Alan Kay puts it - "Simple things should be simple, complex things should be possible". Let's see the simplicity and power of a domain driven API design by looking at this very simple example of a business domain expressed in YAML.

Example

enum:
  CarBrand:
    - Mercedes
    - BMW
    - Audi
    - Porsche
 
entity:
  Car:
    attributes:
      license: Key
      brand: CarBrand!
      mileage: Int!
      color: String

This simple example configuration would generate a

full fledged GraphQL API

• type object for entity
• query for the type (by id)
• query for a list of items of types (with filter, sort and paging)
• filter types for object type
• filter types for all object type fields (e.g. filtering by String)
• create mutation
• update mutation
• delete mutation
• input type for the create mutation
• input type for the update mutation
• result type for create and update mutations
• enumeration type
• resolver for the queries and mutations that read/write to a datastore (per default a document based database)
• statistics queries to get the number of entries, latest updates etc.
• some helper types, queries and more

Some more API Features (not included in this example)

• validation of mutation input (configuration or function)
• relationships between entities
• role based permission management to grant a principal fine-grained access to queries and mutations
• handling of file uploads
• seed data for testing your API or filling the datastore with initial data
• custom code (hooks) to influence the behavior of the resolver
• possible replacement for default implementation of
  • datastore
  • resolver
  • validation
  • file save
  • data seeding
• and more

Let's break the generated GraphQL schema down, to show some of the ActiveQL conventions.

Type

type Car {
  id: ID!
  license: String!
  brand: CarBrand!
  mileage: Int!
  color: String
  createdAt: DateTime!
  updatedAt: DateTime!
}

From the Car entity a GraphQL object type is generated with attributes from the Entity definition becoming fields of this type. As you see, in addition the entity's attributes the type gets a unique id field, that is used to identify an entity item. This id is also used to implement the relationship of entities. The id is assigned by ActiveQL (in fact the actual DataStore implementation) when you call the create mutation.

You might notice that the "license" attribute was configured as type Key but the resulting field is of type String!. Key is in fact an ActiveQL shortcut, for a more complex attribute configuration. Actually all attribute configurations of this example are shortcuts - we will cover this in Attribute Configuration. The attribute "license" could have been written explicitly as

license:
  type: String
  required: true
  unique: true
  updateInput: false
  queryBy: true

Meaning it is a mandatory String field, that will be validated as unique and can only be set in a create mutation but not in an update mutation. Thus making it immutable and allowing it to unambiguously identify an entity item separately from the artificial id. The queryBy configuration will add a carBylicense query to easily get a car by its license.

Every entity type has also createdAt and updatedAt timestamp fields. That are set automatically by the mutation resolvers.

Mutations

type Mutation {
  ping(some: String): String
  seed(truncate: Boolean): String
  createCar(car: CarCreateInput): SaveCarMutationResult
  updateCar(car: CarUpdateInput): SaveCarMutationResult
  deleteCar(id: ID): [String]
}

Any schema includes a mutation ping that simply sends the value back and can be used to test whether a GraphQL API can be accessed without the need to build any specific query or mutation.

There is also a seed mutation you can call to seed the datastore with test or initial data. We did not include any seed data to this example definition, so this would have no effect. For more - check out Seed Configuration.

Entity Mutations

For every entity a create, update and delete mutation is generated - in this example createCar, updateCar and deleteCar.

Input Types

The mutations use input types to hold the value of items that should be created or updated.

input CarCreateInput {
  license: String!
  brand: CarBrand!
  mileage: Int!
  color: String
}
 
input CarUpdateInput {
  id: ID!
  brand: CarBrand
  mileage: Int
  color: String
}

As you see there are separate types generated for the create and update mutations. The CreateType does not have an id while the UpdateType does. The id determines which entity item should be updated.

Also note that the "color" attribute is configured as required in the entity configuration. Therefore it results in a mandatory field in the Car type and in the CarCreateInput type. But not in the CarUpdateInput type - this is because a client is not forced to pass all attributes in the update mutation but only those it wants to change. Making required attributes mandatory in the GraphQL schema for the update input would not allow to leave the others (e.g. "brand" or "mileage") untouched.

You might also have noticed that there is no "license" field in the CarUpdateInput. This is because we have configured the attribute as Key and therefore it is considered to be immutable.

Mutation Result Types

The create and update mutations return different data, depending on whether the operation could be executed or was prevented by validation errors.

type SaveCarMutationResult {
  validationViolations: [ValidationViolation]!
  car: Car
}
 
type ValidationViolation {
  path: String
  message: String!
}

If the mutation could be executed it returns the successfully created/updated entity items.

If there were validation errors it returns a list validation violations to inform an API client about the failed validations. Apart from the unique nature of the "license" attribute we do not have any other validations. See Attribute Validation and Entity Validation how to add business validations.

Please be aware that invalid GraphQL requests, e.g. not providing a mandatory field or having a value that does not match to the field type, will be handled by the GraphQL layer - resulting in an error.

So default mutation can have three possible responses:

Create Mutation

For any entity a create mutation is generated to create new entity items. As we've seen, it uses the create input type for the attribute values and the ValidationViolation type to inform a client about possible validation errors.

type Query {
  ping: String
  car(id: ID): Car
  cars(filter: CarFilter, sort: CarSort, paging: EntityPaging): [Car]
  carBylicense(license: String!): Car
  carsStats(filter: CarFilter): EntityStats
}

input CarFilter {
  id: ID
  brand: StringFilter
  mileage: IntFilter
}

input StringFilter {
  is: String
  isNot: String
  in: [String]
  notIn: [String]
  contains: String
  doesNotContain: String
  beginsWith: String
  endsWith: String
  caseSensitive: Boolean
}
 
input IntFilter {
  is: Int
  isNot: Int
  lowerOrEqual: Int
  lower: Int
  greaterOrEqual: Int
  greater: Int
  isIn: [Int]
  notIn: [Int]
  between: [Int]
}

enum CarSort {
  brand_ASC
  brand_DESC
  mileage_ASC
  mileage_DESC
  id_ASC
  id_DESC
}

input EntityPaging {
  page: Int!
  size: Int!
}

query { cars( sort: mileage_ASC, paging: { page: 0, size: 10 } ) }

query { cars( sort: mileage_ASC, paging: { page: 1, size: 10 } ) }

type EntityStats {
  count: Int!
  createdFirst: Date
  createdLast: Date
  updatedLast: Date
}

  query {
    carsStats( filter: {brand: "Porsche" } ){ count }
  }