Skip to content

GraphQL

GraphQL makes an API for your app from your models. You add annotations to a model, run the builder, and the API is ready.

A GraphQL API has one URL. The client writes the fields that it wants, and it gets JSON with only those fields. To learn GraphQL, read graphql.org/learn.

Install

Run the setup command in your app:

dox add graphql

The command adds the packages, lib/config/graphql.dart and lib/providers/graphql_provider.dart. It does not overwrite a file. For an app with no models, see Without the ORM.

Add a model to the API

Put @GraphQL() on a model. Then add one annotation for each operation that a client can use:

lib/app/models/post/post.model.dart
@DoxModel()
@GraphQL()
@GraphQLAll()
@GraphQLFind()
class Post extends PostGenerator {
  @Column()
  String? title;

  @Column()
  int? userId;

  @BelongsTo(User)
  User? user;
}

@GraphQLAll() adds the posts query, and @GraphQLFind() adds the post query. An operation with no annotation does not exist.

The id, the columns and the relations of the model are fields that a client can ask for. Post has a relation to User, so put @GraphQL() on User also.

Run the builder, and start the app again. Do these two steps after each change to an annotation:

dart run build_runner build

Run a query

A query is a request that reads data. In development, open http://localhost:3000/graphql in a browser. This URL shows GraphiQL, a page where you write and run queries:

{
  posts(limit: 10) {
    title
    user { name }
  }
}

The result has the same shape as the query:

{ "data": { "posts": [{ "title": "Hello GraphQL", "user": { "name": "Ada" } }] } }

Dox loads the users of all ten posts with one database query.

Your client sends the same query as a POST request to /graphql. The JSON body is {"query": "..."}.

All operations

Each annotation adds one query or one mutation. A mutation is a request that changes data.

Annotation GraphQL field Function
@GraphQLAll() posts(limit, offset) Reads a list.
@GraphQLPaginate() posts(first, page) Reads a page of a list, with the total number of rows.
@GraphQLFind() post(id) Reads one row.
@GraphQLCreate(dto:) createPost(input) Adds a row.
@GraphQLUpdate(dto:) updatePost(id, input) Changes a row.
@GraphQLDelete() deletePost(id) Removes a row.

Create and update use a DTO, so the input gets the same validation as your HTTP routes. For each annotation, see Model annotations.

Write your own query

Write your own query when the annotations are not sufficient, for example for a search. Put @GraphQLQuery() on a method of a class in lib/:

lib/app/graphql/post.resolver.dart
class PostResolver {
  @GraphQLQuery()
  Future<List<Post>> latestPosts({int limit = 10}) {
    return Post().orderBy('id', 'desc').limit(limit).get();
  }
}

The method name is the query name, and the parameters are the values that a client can send:

{ latestPosts(limit: 3) { title } }

For more, see Your own resolvers.

Protect the API

By default, all clients can use all operations. Set guard: true on an operation that a guest must not use. Give an ability with can:, and Dox asks the policy of the model before the operation runs:

lib/app/models/post/post.model.dart
@DoxModel()
@GraphQL(filter: Ability.view)
@GraphQLAll(can: Ability.viewAny)
@GraphQLFind(can: Ability.view)
@GraphQLCreate(dto: PostInput, can: Ability.create, guard: true, owner: 'userId')
@GraphQLUpdate(dto: PostInput, can: Ability.update, guard: true)
@GraphQLDelete(can: Ability.delete, guard: true)
class Post extends PostGenerator {}
  • guard: true makes the operation need a login.
  • can: asks the policy if the user can do the operation.
  • filter: hides the rows that the user cannot read.
  • owner: 'userId' sets the owner of a new row to the logged-in user.

A guest that Dox refuses gets the error UNAUTHENTICATED. A user that Dox refuses gets the error FORBIDDEN. The other fields of the request still give their data.

To set this up, see Authentication and Authorization.

Production defaults and limits

In production, GraphiQL and introspection are off, and error details stay on the server. You do not set anything for this.

Limits stop a very large query before it causes much work on your server. For example, a query can nest 64 levels, and a list gives a maximum of 100 rows. Set lower limits when your API is open to the public:

lib/config/graphql.dart
GraphQLConfig graphqlConfig = GraphQLConfig(
  schema: graphqlSchema,
  maxDepth: 10,
  maxNodes: 10000,
);

For all settings, see Configuration.

Model annotations

Each annotation can have these options:

Option Function
name: A different name for the type or the field.
description: The text that GraphiQL shows.
guard: true A client must log in. See Authentication.
can: The policy must allow the user. @GraphQL does not have this option. See Authorization.

@GraphQL

Use it to make the model a type of the API. All other model annotations need it.

@GraphQL()

A model with only @GraphQL() has no queries and no mutations. A client gets it only through a relation, for example post.user.

Dox does not show the fields in the hidden list of the model, so a password stays on the server. To hide a different field, put @GraphQLIgnore() above its @Column().

@GraphQL also has filter:. See Hide rows.

@GraphQLAll

Use it when a client must read a list with limit and offset:

@GraphQLAll()
{ posts(limit: 10, offset: 20) { title } }

The default limit is 20. A limit of more than 100 gives an error.

@GraphQLPaginate

Use it when a client shows pages and needs the total number of rows. The client sends first, which is the number of rows on a page, and page:

@GraphQLPaginate()
{
  posts(first: 10, page: 2) {
    data { title }
    paginatorInfo { total currentPage lastPage hasMorePages }
  }
}
{
  "data": {
    "posts": {
      "data": [{ "title": "Hello GraphQL" }],
      "paginatorInfo": { "total": 11, "currentPage": 2, "lastPage": 2, "hasMorePages": false }
    }
  }
}

The default first is 20, and the default page is 1. A first of more than 100 gives an error.

data has the rows of the page. paginatorInfo has these fields:

Field Value
total The number of rows on all pages.
count The number of rows on this page.
perPage The value of first.
currentPage The number of this page.
lastPage The number of the last page.
hasMorePages true if there is a page after this page.
firstItem The number of the first row of this page. The first row of page 1 is 1. null on an empty page.
lastItem The number of the last row of this page. null on an empty page.

If the model also has @GraphQLAll(), the list is posts and the paged list is postsPaginate. To set a different name, use name::

@GraphQLPaginate(name: 'postPages')

@GraphQLFind

Use it when a client must read one row by its id:

@GraphQLFind()
{ post(id: 1) { title } }

The result is null if no row has that id.

@GraphQLCreate

Use it to let a client add a row. First, write a DTO with the fields that the client can set:

lib/app/dtos/post_input/post_input.dto.dart
@Dto()
class PostInput {
  PostInput({required this.title});

  @MinLength(3, message: 'The title is too short')
  final String title;
}

Then give the DTO to the annotation:

@GraphQLCreate(dto: PostInput)
mutation {
  createPost(input: { title: "My second post" }) { id title }
}

A client can set only the fields of the DTO. Thus, a client cannot set a different column, for example userId.

Dox applies the rules of the DTO before it saves the row. If the input is not correct, Dox saves nothing. The client gets the error VALIDATION_FAILED, with the message for each field in extensions.fields.

Set the owner of a new row

Use owner: when each row belongs to the user that made it. Dox sets that column to the id of the logged-in user:

@GraphQLCreate(dto: PostInput, owner: 'userId')

With owner:, the client must log in to create a row. The owner column must not be a field of the DTO. An update never changes the owner column.

@GraphQLUpdate

Use it to let a client change a row. It can use the same DTO as @GraphQLCreate:

@GraphQLUpdate(dto: PostInput, can: Ability.update, guard: true)
mutation { updatePost(id: 1, input: { title: "A better title" }) { title } }

updatePost changes only the fields that the client sends, and Dox applies only the rules of those fields. The result is null if no row has that id.

Warning

Without can:, each client that can call updatePost or deletePost can change or delete each row. Add can: to @GraphQLUpdate and @GraphQLDelete. The builder shows a warning if one of them has no can: and no guard:.

@GraphQLDelete

Use it to let a client remove a row. It needs no DTO:

@GraphQLDelete(can: Ability.delete, guard: true)
mutation { deletePost(id: 1) }

The result is true, or false if no row has that id.

Authentication

Use guard: true when a client must log in. If your app does not have a login, set it up first with dox add auth.

Add AuthMiddleware() to the config. Dox uses it to read the user:

lib/config/graphql.dart
import 'package:dox_auth/dox_auth.dart';
import 'package:dox_graphql/dox_graphql.dart';
import 'package:my_app/generated/schema.g.dart';

GraphQLConfig graphqlConfig = GraphQLConfig(
  schema: graphqlSchema,
  middleware: <Object>[AuthMiddleware()],
);

The middleware does not stop a request. All fields stay public until you add guard: true. The client sends its token in the Authorization: Bearer <token> header, as usual.

Make a query or mutation need a login

Set guard: true on each operation that a guest must not use:

lib/app/models/post/post.model.dart
@DoxModel()
@GraphQL()
@GraphQLAll()
@GraphQLFind()
@GraphQLCreate(dto: PostInput, guard: true)
@GraphQLUpdate(dto: PostInput, guard: true)
@GraphQLDelete(guard: true)
class Post extends PostGenerator {}

Here, a guest can read posts, but only a logged-in user can change them.

If a guest asks for a guarded field, the guest gets the error UNAUTHENTICATED for that field. The other fields in the same request still give their data.

guard: true needs AuthMiddleware() in the config. Without it, the app stops at start and shows the name of the type or field.

Protect a model everywhere

Write @GraphQL(guard: true) on a model that a guest must never see, for example User:

lib/app/models/user/user.model.dart
@DoxModel()
@GraphQL(guard: true)
@GraphQLFind()
class User extends UserGenerator {}

Then each field that gives a user needs a login. This includes its queries, its mutations, each relation such as post.user, and your own resolvers.

Read the logged-in user

Add a DoxGraphQLContext parameter to a resolver method. The client does not send this value. Dox puts the current request in it:

lib/app/graphql/user.resolver.dart
@GraphQLQuery()
Future<User?> me(DoxGraphQLContext context) {
  return context.user<User>();
}

context.user<User>() gives null for a guest.

Authorization

guard: true is only a login check. Use a policy when the answer is different for each user or each row.

Write a policy

A policy is a class with one method for each rule. The abilities map gives a name to each method. This name is the ability. Ability has the usual names: viewAny, view, create, update and delete.

lib/app/policies/post_policy.dart
import 'package:dox_auth/dox_auth.dart';
import 'package:my_app/app/models/post/post.model.dart';
import 'package:my_app/app/models/user/user.model.dart';

class PostPolicy extends Policy<User, Post> {
  bool update(User user, Post post) => post.userId == user.id;

  @override
  Map<String, Function> get abilities => <String, Function>{
    Ability.update: update,
  };
}

Each ability section below adds one method to this policy. Add each new method to abilities also.

Register the policy

Register the policy in the setup() of a provider. dox add graphql made the GraphQL provider, so you can use it. Keep the super.setup() call:

lib/providers/graphql_provider.dart
class AppGraphQLProvider extends GraphQLProvider {
  AppGraphQLProvider() : super(graphqlConfig);

  @override
  void setup() {
    Gate.policy<Post>(PostPolicy());
    super.setup();
  }
}

The config must have AuthMiddleware(). Without it, Dox cannot read the user, and each client is a guest.

When the app starts, Dox makes sure that the policy has each ability of can: and filter:. If one is missing, the app stops with an error that shows the available abilities:

@GraphQLDelete(can: 'delete') on Post: PostPolicy has no ability 'delete'. Available: update.

Use it on a model

Give an ability to an operation with can:. Dox asks the policy before the operation runs. An operation with no can: does not ask the policy.

lib/app/models/post/post.model.dart
@DoxModel()
@GraphQL(filter: Ability.view)
@GraphQLAll(can: Ability.viewAny)
@GraphQLPaginate(can: Ability.viewAny)
@GraphQLFind(can: Ability.view)
@GraphQLCreate(dto: PostInput, can: Ability.create, guard: true, owner: 'userId')
@GraphQLUpdate(dto: PostInput, can: Ability.update, guard: true)
@GraphQLDelete(can: Ability.delete, guard: true)
class Post extends PostGenerator {}

Some policy methods get a row, and some do not:

Annotation The policy method gets Use
@GraphQLAll(can:), @GraphQLPaginate(can:) The user. Ability.viewAny
@GraphQLCreate(can:) The user. Ability.create
@GraphQLFind(can:) The user and the row. Ability.view
@GraphQLUpdate(can:) The user and the row. Ability.update
@GraphQLDelete(can:) The user and the row. Ability.delete
@GraphQL(filter:) The user and each row. Ability.view

Do not use an ability that needs a row, like Ability.view, on @GraphQLAll, @GraphQLPaginate or @GraphQLCreate.

When the policy refuses a user, the field is null. The other fields keep their data:

{ "data": { "posts": null, "me": { "name": "Ada" } } }

The errors list of the result has one error for posts. Its code is FORBIDDEN, in extensions.code.

viewAny

Use viewAny when some users must not get lists of the model:

@GraphQLAll(can: Ability.viewAny)
bool viewAny(User user) => user.banned != true;

view

Use view when a user can read some rows and not others. Here, a user can read a published post and their own posts:

@GraphQLFind(can: Ability.view)
bool view(User user, Post post) {
  return post.status == 'published' || post.userId == user.id;
}

A refused user gets FORBIDDEN from post(id).

Hide rows

Use filter: on @GraphQL when a client must get only the rows that the user can read:

@GraphQL(filter: Ability.view)

Dox hides each row that the ability refuses, and gives no error. This applies to each field that gives the model:

  • A list, a paged list, or a list relation such as user.posts does not include the row. Thus, a list can have fewer rows than limit.
  • post(id) or a single relation such as comment.post gives null.
  • Your own queries, mutations and fields that return the model do the same.

Warning

filter: does not decide who can change a row. updatePost and deletePost ask only their can:. Give them a can:.

To get null and no error from post(id), use filter: and no can: on @GraphQLFind.

create

Use create when only some users can add a row. The method gets only the user, because no row exists yet:

@GraphQLCreate(dto: PostInput, can: Ability.create)
bool create(User user) => user.verified == true;

Dox asks the policy first. It applies the rules of the DTO only for a user that the policy allows. For a refused user, Dox saves nothing.

update

Use update to decide who can change a row:

@GraphQLUpdate(dto: PostInput, can: Ability.update)
bool update(User user, Post post) => post.userId == user.id;

For a refused user, Dox writes nothing.

delete

Use delete to decide who can remove a row:

@GraphQLDelete(can: Ability.delete)
bool delete(User user, Post post) => post.userId == user.id;

For a refused user, the row stays in the database.

Add your own ability

Use your own ability when the five names of Ability are not sufficient. Write the name as a constant on the policy:

lib/app/policies/post_policy.dart
class PostPolicy extends Policy<User, Post> {
  static const String publish = 'publish';

  bool canPublish(User user, Post post) => user.editor == true;

  @override
  Map<String, Function> get abilities => <String, Function>{
    publish: canPublish,
  };
}
@GraphQLUpdate(dto: PostInput, can: PostPolicy.publish)

Let guests in

A guest is a client that is not logged in. With Policy<User, Post>, Dox refuses each guest with the error UNAUTHENTICATED.

Use Policy<User?, Post> when a guest can read some rows. Then a guest gets to your methods, and user is null:

class PostPolicy extends Policy<User?, Post> {
  bool view(User? user, Post post) {
    if (post.status == 'published') return true;
    return user != null && post.userId == user.id;
  }

  @override
  Map<String, Function> get abilities => <String, Function>{Ability.view: view};
}

Now a guest can read the published posts, and a user can also read their own drafts. To refuse guests on one operation of this model, add guard: true to that operation.

Your own resolvers

A resolver is a method that gives the result of a query or a mutation. Write one when the model annotations are not sufficient. The builder finds each class in lib/ that has a resolver method.

lib/app/graphql/post.resolver.dart
import 'package:dox_graphql/dox_graphql.dart';
import 'package:my_app/app/models/post/post.model.dart';
import 'package:my_app/app/services/post.service.dart';

class PostResolver {
  PostResolver(this.postService);

  final PostService postService;

  @GraphQLQuery()
  Future<List<Post>> trendingPosts({int limit = 10}) {
    return postService.trending(limit);
  }
}

Dox gets the data of the query from the method:

  • The method name is the query name: trendingPosts.
  • The parameters are the values that a client can send. A parameter with a default value is optional.
  • The return type is the type that the client gets.
  • Dox gets the constructor parameters from the container.

A resolver annotation has name:, description: and guard: true, the same as a model annotation.

Write your own mutation

Write your own mutation when one saved row is not sufficient. Put @GraphQLMutation() on a resolver method, and use a DTO for the input:

lib/app/graphql/post.resolver.dart
@GraphQLMutation()
Future<Post> importPost(PostInput input) {
  return postService.import(input);
}

Dox applies the rules of the DTO before your method runs.

Send an error to the client

To send your own message, throw a GraphQLError:

throw GraphQLError('This post is not published yet');

For all other errors, the client sees "Internal server error" in production. Dox sends the real error to the ExceptionHandler of your app.

Check a policy in a resolver

can: works only on the model annotations. To refuse a user in your own resolver, call Gate yourself:

lib/app/graphql/post.resolver.dart
@GraphQLQuery()
Future<Post?> latestPost(DoxGraphQLContext context) async {
  Post? post = await postService.latest();
  User? user = await context.user<User>();
  if (post != null && await Gate.denies(user, Ability.view, post)) {
    throw GraphQLAuth.forbidden();
  }
  return post;
}

GraphQLAuth.forbidden() gives the same FORBIDDEN error as can:. filter: also hides rows in the result of your own resolvers.

Configuration

All settings are fields of GraphQLConfig in lib/config/graphql.dart. Each setting has a default, so set only the settings that you want to change:

lib/config/graphql.dart
GraphQLConfig graphqlConfig = GraphQLConfig(
  schema: graphqlSchema,
  path: '/api/graphql',
);
Setting Default What it does
path /graphql The URL of the API.
middleware none Route middleware, like AuthMiddleware().
graphiql on in development The GraphiQL page.
introspection on in development Lets tools like GraphiQL read the list of your types and fields.
showInternalErrors on in development Sends the real text of an error to the client.
maxDepth 64 How deep a query can nest fields.
maxQueryLength 1000000 The most characters in the text of one query.
maxFields 20000 The most fields one query can ask for.
maxNodes 100000 The most values one request can load.
maxRootFields 50 The most top-level fields in one request. Each alias counts.
maxRelationRows 50000 The most rows that one list relation can load for all parent rows together.

"On in development" means on when APP_ENV is development. For all other values, these three settings are off.

A request that is larger than a max setting gets an error. Set lower values when your API is open to the public.

Without the ORM

If your app does not use models, install with dox add graphql --no-orm. Put @GraphQL() on a plain Dart class. Its public fields are the fields that a client can ask for. You write all the queries yourself:

lib/app/graphql/product.resolver.dart
@GraphQL()
class Product {
  Product({required this.id, required this.name, required this.shopId});

  final int id;
  final String name;

  @GraphQLIgnore()
  final int shopId;
}

class ProductResolver {
  ProductResolver(this.productRepository, this.shopRepository);

  final ProductRepository productRepository;
  final ShopRepository shopRepository;

  @GraphQLQuery()
  Future<List<Product>> products({int limit = 20}) {
    return productRepository.latest(limit);
  }

  @GraphQLResolveField()
  Future<Shop?> shop(Product product, DoxGraphQLContext context) {
    DataLoader<int, Shop> shops = context.loader<int, Shop>(
      'shops',
      () => DataLoader<int, Shop>(shopRepository.findByIds),
    );
    return shops.load(product.shopId);
  }
}

@GraphQLResolveField() adds a field to the class of its first parameter. Thus, Product gets a shop field, and Shop also needs @GraphQL().

The DataLoader collects the shop ids of the full request. Thus, fifty products cause one shop query, not fifty queries. findByIds takes a List<int> and returns a Future<List<Shop?>>, in the same order as the ids.

Details

  • GET requests. A client can also send a query as a GET request, with query in the URL. A mutation needs POST.
  • Computed fields. Put @GraphQLField() on a getter of a @GraphQL class to make the getter a field. It has guard: true also.
  • Field types. A field can be a String, int, double, bool, DateTime, an enum, a @GraphQL class, or a List of them. A different type stops the build. Put @GraphQLIgnore() on a field that the API does not need.
  • Paged lists with filter:. data and count do not include the hidden rows. total and lastPage include them.
  • Results of mutations with filter:. createPost always gives the new row. updatePost saves a hidden row, but its result is null.
  • Filtered types. A field can give a model with filter: as Post, Post?, List<Post> or List<Post>?. A different shape stops the build.
  • An id that does not exist. With can:, Dox asks the policy about an empty row. Thus, a refused user gets FORBIDDEN for each id. If your policy method allows an empty row, a client can find which ids exist.
  • Your own AuthMiddleware. If you use a subclass of AuthMiddleware, override asOptional() to return your subclass. If you do not, your changes do not run.