Schema Directives

The GraphQL standard supports extensions using directives. These can be used in the schema file to change how that is being loaded and transformed.

REST Directive

In addition to the Annotations / Decorators, it is also possible (for simpler use cases) to use a REST directive to call another API. If this directive is used in the GraphQL schema, it automatically does the REST call using the configured input parameters.

The following parameters are supported:

  • path - the relative path to the api, same path as used when calling an api. Example: "/BaaSApi/baasservices/..service../..resource../api/v1/books/{id}"
  • method - for example GET or POST. GET is the default if not specified
  • headers - a list of headers to be included. Example: ["accept: application/json"]
  • body - a string that is used as an input in a POST or PUT for example
  • rolesAllowed - if certain roles are required; works the same way as the annotation used on REST methods. Example: ["authenticated"]
  • responseClass - this is for Java only and uses the full class name. These classes can either be created manually or by generating code from an OpenApi file. Usage of this is optional, only use if needed.
    Example
    "com.baas.graphqljava.services.GraphQLResolver.Book" or "[com.baas.graphqljava.services.GraphQLResolver.Book]" for array data.
    Both "path" and "body" supports replacements variables, like the "{id}" in the path above. These are replaced with data from the current context that matches this name. The directive can be placed after any field and is then triggered when data is loaded for that field.
Example - GraphQL schema
Here is an example that loads a Book from a REST api. The directive is placed on the "bookById" field.
```json
type Query {
 bookById(id: ID): Book
 @rest(
 path: "/BaaSApi/baasservices/customer/restgraphql/api/v1/books/{id}"
 rolesAllowed: ["authenticated"]
 headers: ["accept: application/json"]
 )
}
```

Map Directive

The Map directive supports transforming an array to an object. This is useful when a query needs to target a certain element in the array.

The following parameters are supported:

  • key - the field to use as key
  • value - (optional), the field to use as value, if not specified, the whole array element is added as the value
  • fallback - (optional), if the key field doesn't exist or is empty, this can be used as fallback
Example - IDM
A Json for resources for an IDM document might look like this:
```json
"resrs": {
 "res": [{
 "name": "",
 "mimetype": "image/jpeg"
 }, {
 "name": "Preview"
 "mimetype": "image/png"
 }
 ]
}
```

To be able to only select the mimetype for the main resource (the one with an empty name) in the GraphQL query, the schema can be created like this:

```json
type Item {
 filename: String
 size: String
 resrs: Resources
}
type Resources {
 res: Resource @map(key: "name" value: "mimetype" fallback: "Main")
}
type Resource {
 Main: String
 Preview: String
}
```

Limit Directive

The Limit directive limits the number of elements that are returned in an array. This can be used to optimize performance by limiting the number of objects that are loaded.

If the source is not an array, null is returned.

The following parameters are supported: size - the maximum number of elements to return in an array.

First Directive

The First directive returns the first element from an array. This is similar to using the Limit directive with size=1, but this returns an object instead of an array. For example, this can be useful when used with as REST resource and the "filter" parameter.

If the source is not an array, null is returned.

No parameters are supported.