StepZen Directives Reference

endpoint

This value is required. The endpoint argument specifies the URL for the HTTP request. Endpoint is a string value that can contain variables preceded by a $, which are replaced by StepZen. These variables can match query arguments or variables in a corresponding configuration of the same name. For example, $username in the endpoint string will be replaced by the value of a username query argument.

By default, StepZen automatically appends all query arguments to the endpoint URL query string (except when using POST endpoints with a default postbody). All argument values are automatically URL-encoded so that when querying your StepZen GraphQL endpoint you can safely pass any argument "as is".

For example, in the following schema the actual endpoint URL is https://httpbin.org/anything?number=$number&message=$message.

type Query {
  echo(number: Int, message: String): EchoResponse
    @rest(endpoint: "https://httpbin.org/anything")
}

If you want to disable this default and take full control over the endpoint URL, add a configuration to your @rest directive that sets the stepzen.queryextensionguard attribute to true (in config.yaml). For example, with in the following schema only the message argument is appended to the endpoint URL:

type Query {
  echo(number: Int, message: String): EchoResponse
    @rest(
      endpoint: "https://httpbin.org/anything?message=$message"
      configuration: "your_config_name"
    )
}

configurationset:
  - configuration:
      name: "your_config_name"
      stepzen.queryextensionguard: true

There is a special value for endpoint stepzen:empty that can be used in conjunction with the ecmascript argument. stepzen:empty configures the StepZen server to make no http request, but still process the ecmascript argument, allowing you to create responses entirely from ecmascript.

configuration

This value is optional. The connection details to pass down into headers (e.g. authorization) - specifying to StepZen which configuration to use for this endpoint. StepZen configurations are stored in a config.yaml file and are assigned names.

For example, a named configuration within config.yaml called github_config will be referenced by a configuration property of @rest as configuration: github_config. A configuration can contain things like API keys needed to connect to a REST API or other configuration values that may be needed to construct the endpoint URL.

method

This value is optional. The default value for method is GET, other values can be DELETE, PATCH, POST, or PUT. If postbody is set on @rest, then the default changes to POST. The selection of method affects the configuration properties you can use.

type Mutation {
  sendPostRequest(to: String!, from: String!, template_id: String!): Email
    @rest(method: POST, endpoint: "https://api.sendgrid.com/v3/mail/send")
}

resultroot

This value is optional. In cases where the data to populate the GraphQL type is not in the root object of the result from a REST API, use resultroot to specify the path that StepZen is to use as the root.

Let's look at an example. This is the structure of a response from the Contentful Delivery API:

{
  "fields": {
    "title": {
      "en-US": "Hello, World!"
    },
    "body": {
      "en-US": "Bacon is healthy!"
    }
  },
  "metadata": {
    // ...
  },
  "sys": {
    // ...
  }
}

In this example, fields contains all the data to populate a type representing this content object. Therefore, resultroot is set to fields as shown here:

contentfulPost(id: ID!): Post
    @rest(
      endpoint: "https://cdn.contentful.com/spaces/$spaceid/entries/$id"
      resultroot: "fields"
      configuration: "contentful_config"
    )

Important: The value of setters is mapped from the resultroot. In this example, this makes the data under metadata and sys inaccessible.

In some cases, the data to populate the GraphQL type is located inside of an array of items of the result from a REST API. Therefore, you must set the resultroot inside of an array of items:

{
  "sys": { "type": "Array" },
  "skip": 0,
  "limit": 100,
  "total": 1256,
  "items": [
    {
      "fields": {
        /* list of fields for this entry */
      }
    }
  ]
}

In the preceding example, Contentful returns all the entries and we need to set the value of the root to fields inside the array of items.

You can do this by adding an empty array notation in the resultroot as in the following example:

contentfulBlogs: [Blog]
    @rest(
      endpoint: "https://cdn.contentful.com/spaces/$spaceid/entries"
      resultroot: "items[].fields"
      configuration: "contentful_config"
    )

setters

This value is optional. Sometimes the name or structure of the content returned by a REST API doesn't exactly match the GraphQL type that the query will populate. In these cases, you can use setters to map the values returned by a REST API result to the appropriate fields within the returned GraphQL type. (Only fields that need to be remapped need to be specified, otherwise StepZen makes good default assumptions.)

setters takes an array of objects each containing a field and path. The field is the property in the GraphQL type returned by the query that the value of field should be set to. The path is the path to the value in the endpoint's JSON result.

To illustrate this concept, let's look at the following example JSON response:

{
  "id": 194541,
  "title": "The Title",
  "slug": "the-url-2kgk",
  "published_at": "2019-10-24T13:52:17Z",
  "user": {
    "name": "Brian Rinaldi",
    "username": "remotesynth"
  }
}

If the corresponding Article GraphQL type has a field of published but not published_at, StepZen will not be able to automatically map the value returned by the REST API to the value in the GraphQL type.

To resolve this, add a setter with the following values:

{ field: "published", path: "published_at" }

Setters are also useful for mapping values in nested objects, returned by a REST API.

In the example preceding, the value of user.name cannot be automatically mapped to a field in the GraphQL type. You have two options:

• Create another type for User that has the corresponding fields and then use the resultroot property to user.
• Flatten the values and add them to the Article type using the following setters:

{ field: "author", path: "user.name" }
{ field: "username", path: "user.username" }

Here's an example of a @rest directive in a file called article.graphql:

type Article {
  id: ID!
  title: String!
  description: String
  cover_image: String
  username: String!
  github_username: String!
}
type Query {
  myArticles(username: String!): [Article]
    @rest(
      endpoint: "https://dev.to/api/articles?username=$username"
      configuration: "dev_config"
      setters: [
        { field: "username", path: "user.username" }
        { field: "github_username", path: "user.github_username" }
      ]
    )
  }
}

Let's pull out the @rest directive to take a closer look:

@rest(
  endpoint: "https://dev.to/api/articles?username=$username"
  configuration: "dev_config"
  setters: [
    { field: "username", path: "user.username" }
    { field: "github_username", path: "user.github_username" }
  ]
)

endpoint, configuration, and setters are all arguments to the @rest directive. That is, they give StepZen the information it needs to connect to the REST API:

• endpoint sets the endpoint of the API.
• configuration references the configuration file by its name value.
• setters specifies the names of the fields that will be used and their values from their paths.

Character that are not numbers, letters, or underscores If the value for a path in setters contains any character that is not a number, letter, or underscore, you must wrap the value with back-ticks. For example:

The path value in: { field: "terminal", path: "terminal-name" }

must be wrapped in back ticks so the line reads as: { field: "terminal", path: "`terminal-name`" }

Note that the value accepts template literals, but the field will not, for example, { field: "`terminal`", path: "`terminal-name`" } will not work.

filter

This value is optional. The filter argument will filter results returned from the REST API based on a condition so that the query will only returned the filtered results. It accepts any boolean operator (e.g. ==, !=, >. <, >=, <=).

For example, the following filter returns only the record for the email that matches the string:

newsletterList: [Subscriber]
@rest(
    endpoint: "https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions"
    filter: "email==\"quezarapadon@quebrulacha.net\""
)

Note: Special characters, like the preceding quotes, need to be escaped with \. Using variables within a filter condition are not supported at this time.

headers

This value is optional. The headers argument specifies headers as name and $variable. Variables are passed into header fields from the configuration or arguments in the query

@rest(
  headers: [
    { name: "Authorization" value: "Bearer $bearerToken" }
  ]

In this example, the $bearerToken variable can come from a configuration or a query argument.

forwardheaders

This value is optional. This defines the list of headers forwarded from the incoming GraphQL HTTP request to the HTTP call made to endpoint. Nonexistent headers will forward as an empty header. Headers rendered via configuration entries take priority.

@rest(
  forwardheaders: ["Authorization", "User-Agent"]

In this example, the HTTP call made to the endpoint will include the Authorization and User-Agent headers from the incoming GraphQL HTTP request.

postbody

This value is optional. You set postbody when you need customize the automatically generated body for a PATCH, POST, or PUT request. Let's look at some examples to help explain how this argument can be used.

StepZen automatically generates the request body using all query or mutation arguments. For example, consider a query defined as follows:

type Query {
  formPost(firstName: String! lastName: String!): JSON
    @rest(
      method: POST
      endpoint: "https://httpbin.org/post"
    )
}

This query accepts two string values and returns a JSON scalar. The contenttype has not been set, so defaults to application/json. The postbody has not been set, so StepZen automatically generates a simple JSON body using the query argument names and values:

{
  "firstName":"value",
  "lastName":"value"
}

If we change the contenttype to application/x-www-form-urlencoded, StepZen generates a form-encoded request body request body.

type Query {
  formPost(firstName: String! lastName: String!): JSON
    @rest(
      method: POST
      contenttype: "application/x-www-form-urlencoded"
      endpoint: "https://httpbin.org/post"
    )
}

The preceding schema code results in a body of:

firstName=value&lastName=value

If you need to change the field names in the automatically generated bodies, you can do that using the arguments attribute for the directive. In the following example we have changed the names from camelCase to snake_case:

type Query {
  formPost(firstName: String! lastName: String!): JSON
    @rest(
      method: POST
      endpoint: "https://httpbin.org/post"
      arguments: [
        {argument:"firstName", name:"first_name"},
        {argument:"lastName", name:"last_name"}
      ]
    )
}

This works for both application/json and x-www-form-urlencoded bodies.

We only need to use postbody when we need to customize the request body more than simply renaming fields. For example, if we need to add fields, or generate a more complex structure. When performing variable substitution in the postbody, we need to use the Go language template syntax.

For example, consider a query that uses the Client Credentials flow to obtain an OAuth token. Since the grant_type argument is not included in the query definition, we need to add it to the request body.

type Query {
  token(client_id: String! client_secret: String!): Token
    @rest(
      endpoint: "<oauth token endpoint"
      method: POST
      contenttype: "x-www-form-urlencoded"
      postbody: """
      grant_type=client_credentials&client_id={{ .Get "client_id" }}&client_secret={{ .Get "client_secret"}}
      """
    )
}

Consider a JSON payload from our earlier example, but our JSON payload needs to be more complex:

{"user":{
  "firstName": "first name"
  "lastName": "last name"
  }
}

type Query {
  logUser(firstName: String! lastName: String!): JSON
    @rest(
      endpoint: "https://httbin.org/post"
      postbody: """
      {
        "user": {
          "firstName": "{{ .Get "firstName" }}",
          "lastName": "{{ .Get "lastName" }}"
        }
      }
      """
    )
}

As we are not automatically generating the body of the request, the GraphQL query arguments are automatically appended to the request URL as as parameters in a query string, e.g. https://httpbin.org/post?firstName=<value>&lastName=<value>. We can tell StepZen not to append GraphQL query arguments as query string parameters by setting the stepzen.queryextensionguard attribute to true in the config.yaml file as follows:

configurationset:
  - configuration:
      name: "config"
      stepzen.queryextensionguard: true

Our final query schema is:

type Query {
  logUser(firstName: String! lastName: String!): JSON
    @rest(
      endpoint: "https://httbin.org/post"
      postbody: """
      {
        "user": {
          "firstName": "{{ .Get "firstName" }}",
          "lastName": "{{ .Get "lastName" }}"
        }
      }
      """
      configuration: "config"
    )
}

PATCH with autopostbody works for the simplest form of patch using nullable arguments.

type Mutation {
  updateUser_Optionals(first_name: String last_name: String): JSON
    @rest(
      endpoint: "https://httpbin.org/patch"
      method: PATCH
    )
}

Query:

mutation stepzenPatch {
  updateUser_Optionals(first_name: "John", last_name: "Doe")
}

To pass JSON as an argument in the GraphQL Mutation, the argument JSONPatch must be added as a variable to the postbody argument:

type Mutation {
  updateUser_PatchString(JSONPatch: String): JSON
    @rest(
      endpoint: "https://httpbin.org/patch"
      method: PATCH
      postbody: """{{ .Get "JSONPatch" }}"""
    )
}

Query:

mutation MyMutation {
  updateUser_PatchString(JSONPatch: "{\"name\":\"John\"}")
}

An example of when updateUser_PatchString would be used rather than updateUser_Optionals is when an application or operation, such as @sequence, passes JSON as an argument.

The JSONPatch can also be built using the JSON scalar type in which case, the following works:

type Mutation {
  updateUser_Patch(JSONPatch: JSON): JSON
    @rest(
      endpoint: "https://httpbin.org/patch"
      method: PATCH
      postbody: """{{ .GetJSON "JSONPatch" }}"""
    )

DELETE does automatic query string extension, passing all GraphQL arguments by default. postbody may be specified if needed; there is no postbody autogeneration.

type Mutation {
  deleteUser(userID: ID!): JSON
    @rest(
      endpoint: "https://httpbin.org/delete"
      method: DELETE
    )
}

The query would result in the following URL being called with DELETE https://httpbin.org/delete?userID=1

mutation MyMutation {
  deleteUser(userID: "1")
}

cachepolicy

This value is optional. The cachepolicy property overrides the default cache behavior.

In StepZen, caching is automatic. The system knows when the backend call is a REST call and sets up a cache with a default time-to-live (TTL) of one minute. Because StepZen uses multiple servers to handle traffic, these caches are available within the execution of a query and across queries.

cachepolicy can be set to the following values:

• DEFAULT : Default cache strategy. The DEFAULT strategy varies according to field and method.

  If applied to a field of Query the default is { strategy: DEFAULT } and:

  • When method=GET the default is { strategy: ON }.
  • When method=PATCH the default is { strategy: OFF }
  • When method=POST the default is { strategy: OFF }.
  • When method=PUT the default is { strategy: OFF }
  • When method=DELETE the default is { strategy: OFF }

  If applied to a Mutation field, the default is { strategy: OFF }.

• ON : Use cache.

• OFF : Ignore cache.

• FORCE : The request is forced and the result is placed in the cache.

@rest(
  endpoint: "yourendpoint.com",
  cachepolicy: { strategy: ON }
)

transforms

This value is optional. The transforms argument "transforms" the @rest JSON response. The transforms argument takes the following form:

transforms: [{pathpattern: "...", editor: "..."},
             {pathpattern: "...", editor: "..."},
             ...]

The transforms argument of the @rest directive takes a list of objects of the form {pathpattern: "...", editor: "..."}. This list must contain at least one object. If there is more than one object, they are processed in the order in which they appear, the output of one providing the input for the next.

The pathpattern as the name implies specifies what objects are included in the transform processing by specifying the allowed paths. Here are the ways to select a JSON path:

• term matches a specific object key, like pathpattern:["records"].
• [num] matches a specific array index, like pathpattern:["records",[2]].
• <> matches exactly one object key.
• [] matches exactly one array index.
• * matches either exactly one key, or a exactly one index.
• <>* matches a sequence of zero or more keys, like pathpattern:["records", "<>*"] would match records, records.name, and including those nested like records[1].name, records.artist.name, etc.
• []* matches a sequence of zero or more indices.
• ** matches a sequence of zero or more anything, keys or indices. pathpattern:[] (an empty pathpattern) indicates that the editor should be applied at the root.

Available editors are listed in the following section. All of the editors except xml2json expect JSON input. xml2json expects XML input. The transforms are applied in the order they appear in the transforms argument in the schema.

• xml2json : Transform XML to JSON.

  SOAP backends commonly return XML. The following transforms argument will properly transcribe an XML response to JSON.

   transforms: [{pathpattern: [], editor: "xml2json"}]
  

  The following rules apply to the xml2json editor:

  • if an xml2json editor is present, it must be specified in the first or only input object.
  • if the REST response (or the output of any preceding ecmascript transform) produces an XML value, then there must be a transform argument, and the xml2json editor must be the first input object.
  • the only valid pathpattern that can accompany an xml2json editor is [] (root) since the input is not JSON

• jq:<jq formula> : Apply a jq formula to the JSON.

  Tip: You can can also test out your jq formula against the entire tree using any of the jq online tools (such as jqplay) and then copy the jq formula directly into your StepZen schema, often without any changes. Make pathpattern:[] in this case. While this approach often works, sometimes jq treatment of arrays etc. differs subtly, so you might have to modify the formula that works outside StepZen a bit for it to work inside StepZen.

  To manipulate the following JSON response.

  [
    {
      "city": "Miami",
      "name": "John Doe"
    }
  ]
  

  This transforms argument manipulates the JSON response, applying the jq formula .[]|{name,address:{city:.city}}.

    transforms: [{pathpattern:[],editor:"jq:.[]|{name,address:{city:.city}}"}]
  

  To place the field, city, as a field in the new nested object, address.

  {
    "data": {
      "customers": [
        {
          "name": "John Doe",
          "address": {
            "city": "Miami"
          }
        }
      ]
    }
  }
  

• jsonata:<jsonata expression> : Apply a jsonata expression to the JSON.

  Similar to the jq editor, the jsonata editor allows you to manipulate the JSON response. You can learn more about jsonata at https://jsonata.org/, and there is an online jsonata playground that you can use to test your jsonata expressions.

• objectToArray : Transform a list of key-values pairs to an array.

  Many backends return a list of key-values pairs with field names representing the key, as opposed to an array. So one might get a response back that looks like:

  {
    "data": {
      "2333": {
        "name": "john doe",
        "age": 23
      },
      "3333": {
        "name": "jane smith",
        "age": 21
      }
    }
  }
  

  The classic GraphQL conversion of this will generate a new type for each entry which is not viable. The objectToArray editor addresses this issue.

  @rest (endpoint: "...", transforms: [
    {pathpattern: ["data","<>*"], editor: "objectToArray"}
  ])
  

  This configures StepZen to take an occurrence of zero or more keys at the path "data" and apply the transform (the expression "<>*" is the expression that you will use almost always, though other possibilities exist — see the preceding description on pathpattern wildcard syntax).

  This will produce:

  {
    "data": [
          {
            "name": "2333",
            "value": {
              "age": 23,
              "name": "john doe"
            }
          },
          {
            "name": "3333",
            "value": {
              "age": 21,
              "name": "jane smith"
            }
          }
        ]
  }
  

  Now you can treat it as an array of objects that can be processed by downstream @rest directive arguments.

• drop : prunes the JSON tree.

  Supposing you had two queries:

  type Query {
    anonymous: [Customer]
    known: [Customer]
  }
  

  where in the anonymous query, you did not want the name field to be present. How would you achieve it against the same customer API? You could declare two types, type Anonymous which does not have the name field and type Customer which does, and then have each preceding query return those two types respectively. But an easier answer is to just prune name away from the JSON response in the first query, and as a result, there is no way it will get populated.

  type Query {
    anonymous: [Customer]
    @rest (endpoint: "https://introspection.apis.stepzen.com/customers",
      transforms: [
      {pathpattern: ["[]","name"], editor: "drop"}])
    known: [Customer]
    @rest (endpoint: "https://json2api-customers-zlwadjbovq-uc.a.run.app/customers")
  }
  

• rename:<old-name>,<new-name> : Rename a field.

  {
  "item": {
    "$id": 23
    }
  }
  

  To rename the $id field add the following transforms argument. Identify the location of the field in the pathpattern and rename the field in the editor.

    transforms: [{pathpattern: ["item"], editor: "rename:$id,id"}]
  

  The transformed JSON will be:

  {
    "item": {
      "id": 23
    }
  }
  

ecmascript

This argument enables you to run ECMAScript 5.1 scripts to manipulate the HTTP request and response bodies.

There are two function signatures you can implement:

• bodyPOST(s) : manipulates the HTTP request body
• transformREST(s) manipulates the HTTP response body, s.

Each function signature has a built in function get which allows retrieving arguments. Refer to the following example:

type Query {
  scriptExample(message: String!): JSON
  @rest(
    endpoint: "https://httpbin.org/anything"
    method: POST
    ecmascript: """
      function bodyPOST(s) {
        let body = JSON.parse(s);
        body.ExtraMessage = get("message");
        return JSON.stringify(body);
      }

      function transformREST(s) {
        let out = JSON.parse(s);
        out.CustomMessage = get("message");
        return JSON.stringify(out);
      }
    """
  )
}

In this schema, we are sending an HTTP POST request to https://httpbin.org/anything. The payload of the request is modified using the bodyPOST function, adding an "ExtraMessage" field that contains the contents of the "message" argument. The response is modified using the transformREST function, adding a "CustomMessage" field that also contains the contents of the "message" argument.

Tip: When using ecmascript (or for that matter, any transforms), it is insightful to initially set the return type of the query to be JSON, which allows you to test and fix errors. Then you can set the return type to be a specific schema type.

Bonus Tip: You can use ecmascript to simulate a REST API response.

You can use ecmascript combined with the endpoint stepzen:empty to simulate a REST API response. See the following example:

type Query {
  customers: JSON
  @rest (
    endpoint: "stepzen:empty",
    ecmascript: """
      function transformREST(s) {
          return (JSON.stringify({
                                  "records": [
                                    {"name": "John Doe", "countryRegion": "US"},
                                    {"name": "Jane Smith", "countryRegion": "UK"}
                                  ]
                                  }))
      }
    """
  )
}

Leaf fields

When applied to a field selection that is a list of a scalar or enum type (for example [String]) then @sort sorts the value of the list.

For example the result of this query:

query {
  products {
    tags # ['c', 'b', 'a', null]
  }
}

Will be transformed to this:

query {
  products {
    tags @sort # [null, 'a', 'b', 'c']
  }
}

The sort order is ascending, with null values sorted first.

Object fields

When applied to a field selection that is a list of an object or interface type then @sort sorts the list of objects.

The sort order is derived from the direct sub-selection of the @sort field selection.

For example this query will sort customers by lastName first, then firstName and then email in ascending order for each field, with null values sorted first.

query {
  customers @sort {
    lastName
    firstName
    email
  }
}

Fields can be selected but omitted from the sort order by selecting them in a fragment. This query will only sort by lastName, since firstName and email are in an inline fragment, and thus are not the direct sub-selection of customers.

query {
  customers @sort {
    lastName
    ... {
      firstName
      email
    }
  }
}