Add GraphQL service support (#364)

* feat(spec): add GraphQL service support

Signed-off-by: Nathan Ribeiro <[email protected]>

* feat(graphql): mention workflow expression support for arguments

Signed-off-by: Nathan Ribeiro <[email protected]>

* fix(graphql): add graphql to the type enum on the function definition

Signed-off-by: Nathan Ribeiro <[email protected]>

* fix(graphql): correctly label the JSON for the mutation function def and ref

Signed-off-by: Nathan Ribeiro <[email protected]>

* fix(graphql): removing the word caveat from the spec since we are defining proper usage in the first place

Signed-off-by: Nathan Ribeiro <[email protected]>

* fix(graphql): better wording on various points

Signed-off-by: Nathan Ribeiro <[email protected]>

* small updates to properties so can be validated

Signed-off-by: Tihomir Surdilovic <[email protected]>

Co-authored-by: Tihomir Surdilovic <[email protected]>

Author: lynxnathan

roadmap/README.md

@@ -30,6 +30,7 @@ _Status description:_
 | ✔️| Removed `workflowId` from ParallelState and ForEach states (use subFlow action instead) | [spec doc](../specification.md) |
 | ✔️| Add subflow actions `version` property | [spec doc](../specification.md) |
 | ✔️| Renamed `schemaVersion` to `specVersion` and it is now a required parameter | [spec doc](../specification.md) |
+| ✔️| Add GraphQL support for function definitions | [spec doc](../specification.md) |
 | 🚩 | Workflow invocation bindings |  |
 | 🚩 | CE Subscriptions & Discovery |  |
 | 🚩 | Error types | [issue](https://github.com/serverlessworkflow/specification/issues/200) | 

schema/functions.json

@@ -36,15 +36,16 @@
         },
         "operation": {
           "type": "string",
-          "description": "If type is `rest`, <path_to_openapi_definition>#<operation_id>. If type is `rpc`, <path_to_grpc_proto_file>#<service_name>#<service_method>. If type is `expression`, defines the workflow expression.",
+          "description": "If type is `rest`, <path_to_openapi_definition>#<operation_id>. If type is `rpc`, <path_to_grpc_proto_file>#<service_name>#<service_method>. If type is `graphql`, <url_to_graphql_endpoint>#<literal \"mutation\" or \"query\">#<query_or_mutation_name>. If type is `expression`, defines the workflow expression.",
           "minLength": 1
         },
         "type": {
           "type": "string",
-          "description": "Defines the function type. Is either `rest`, `rpc` or `expression`. Default is `rest`",
+          "description": "Defines the function type. Is either `rest`, `rpc`, `graphql` or `expression`. Default is `rest`",
           "enum": [
             "rest",
             "rpc",
+            "graphql",
             "expression"
           ],
           "default": "rest"

schema/workflow.json

@@ -359,8 +359,9 @@
                 },
                 "arguments": {
                   "type": "object",
-                  "description": "Function arguments"
-                }
+                  "description": "Function arguments/inputs"
+                },
+                "selectionSet": "Only used if function type is 'graphql'. A string containing a valid GraphQL selection set"
               },
               "additionalProperties": false,
               "required": [

specification.md

@@ -76,8 +76,8 @@ For more information on the history, development and design rationale behind the
 <img src="media/spec/spec-parts.png" width="600" alt="Serverless Workflow Specification Focus On Standards"/>
 </p>
 
-Serverless Workflow language takes advantage of well-established and known standards such as [CloudEvents](https://cloudevents.io/), [OpenApi](https://www.openapis.org/) specifications,
-and [gRPC](https://grpc.io/).
+Serverless Workflow language takes advantage of well-established and known standards such as [CloudEvents](https://cloudevents.io/), [OpenAPI](https://www.openapis.org/) specifications,
+[gRPC](https://grpc.io/) and [GraphQL](https://graphql.org/).
 
 ## Project Components
 
@@ -950,12 +950,13 @@ Merging number types should be done by overwriting the data from events data/act
 
 ### Workflow Functions
 
-Workflow [functions](#Function-Definition) are reusable definitions for RESTful service invocations and/or expression evaluation.
+Workflow [functions](#Function-Definition) are reusable definitions for service invocations and/or expression evaluation.
 They can be referenced by their domain-specific names inside workflow [states](#State-Definition).
 
 Reference the following sections to learn more about workflow functions:
 * [Using functions for RESTful service invocations](#Using-Functions-For-RESTful-Service-Invocations)
-* [Using functions for RPC service invocation](#Using-Functions-For-RPC-Service-Invocations)
+* [Using functions for gRPC service invocation](#Using-Functions-For-RPC-Service-Invocations)
+* [Using functions for GraphQL service invocation](#Using-Functions-For-GraphQL-Service-Invocations)
 * [Using functions for expression evaluations](#Using-Functions-For-Expression-Evaluation)
 
 ### Using Functions For RESTful Service Invocations
@@ -1069,6 +1070,7 @@ In our workflow definition, we can then use function definitions:
 ```
 
 Note that the `operation` property has the following format: 
+
 ```text
 <URI_to_proto_file>#<Service_Name>#<Service_Method_Name>
 ```
@@ -1077,9 +1079,154 @@ Note that the referenced function definition type in this case must be `rpc`.
 
 For more information about functions, reference the [Functions definitions](#Function-Definition) section.
 
+### Using Functions For GraphQL Service Invocations
+
+If you want to use GraphQL services, you can also invoke them using a similar syntax to the above methods.
+
+We'll use the following [GraphQL schema definition](https://graphql.org/learn/schema/) to show how that would work with both a query and a mutation:
+
+```graphql
+type Query {
+    pets: [Pet]
+    pet(id: Int!): Pet
+}
+
+type Mutation {
+    createPet(pet: PetInput!): Pet
+}
+
+type Treat {
+    id: Int!
+}
+
+type Pet {
+    id: Int!
+    name: String!
+    favoriteTreat: Treat
+}
+
+input PetInput {
+    id: Int!
+    name: String!
+    favoriteTreatId: Int
+}
+```
+
+#### Invoking a GraphQL `Query`
+
+In our workflow definition, we can then use a function definition for the `pet` query field as such:
+
+```json
+{
+  "functions": [
+    {
+      "name": "getOnePet",
+      "operation": "https://example.com/pets/graphql#query#pet",
+      "type": "graphql"
+    }
+  ]
+}
+```
+
+Note that the `operation` property has the following format for the `graphql` type:
+
+```text
+<url_to_graphql_endpoint>#<literal "mutation" or "query">#<mutation_or_query_field>
+```
+
+In order to invoke this query, we would use the following `functionRef` parameters:
+
+```json
+{
+  "refName": "getOnePet",
+  "arguments": {
+    "id": 42
+  },
+  "selectionSet": "{ id, name, favoriteTreat { id } }"
+}
+```
+
+Which would return the following result:
+
+```json
+{
+  "pet": {
+    "id": 42,
+    "name": "Snuffles",
+    "favoriteTreat": {
+      "id": 9001
+    }
+  }
+}
+```
+
+#### Invoking a GraphQL `Mutation`
+
+Likewise, we would use the following function definition:
+
+```json
+{
+  "functions": [
+    {
+      "name": "createPet",
+      "operation": "https://example.com/pets/graphql#mutation#createPet",
+      "type": "graphql"
+    }
+  ]
+}
+```
+
+With the parameters for the `functionRef`:
+
+```json
+{
+  "refName": "createPet",
+  "arguments": {
+    "pet": {
+      "id": 43,
+      "name":"Sadaharu",
+      "favoriteTreatId": 9001
+    }
+  },
+  "selectionSet": "{ id, name, favoriteTreat { id } }"
+}
+```
+
+Which would execute the mutation, creating the object and returning the following data:
+
+```json
+{
+  "pet": {
+    "id": 43,
+    "name": "Sadaharu",
+    "favoriteTreat": {
+      "id": 9001
+    }
+  }
+}
+```
+
+Note you can include [expressions](#Workflow-Expressions) in both `arguments` and `selectionSet`:
+
+```json
+{
+  "refName": "getOnePet",
+  "arguments": {
+    "id": "${ .petId }"
+  },
+  "selectionSet": "{ id, name, age(useDogYears: ${ .isPetADog }) { dateOfBirth, years } }"
+}
+```
+
+Expressions must be evaluated before executing the operation.
+
+Note that GraphQL Subscriptions are not supported at this time.
+
+For more information about functions, reference the [Functions definitions](#Function-Definition) section.
+
 ### Using Functions For Expression Evaluation
 
-In addition to defining RESTful and RPC services and their operations, workflow [functions definitions](#Function-Definition)
+In addition to defining RESTful, RPC and GraphQL services and their operations, workflow [functions definitions](#Function-Definition)
 can also be used to define expressions that should be evaluated during workflow execution.
 
 Defining expressions as part of function definitions has the benefit of being able to reference
@@ -1713,7 +1860,7 @@ not obeyed in the workflow definition.
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
 | name | Unique function name | string | yes |
-| operation | If type is `rest`, <path_to_openapi_definition>#<operation_id>. If type is `rpc`, <path_to_grpc_proto_file>#<service_name>#<service_method>. If type is `expression`, defines the workflow expression. | string | no |
+| operation | If type is `rest`, <path_to_openapi_definition>#<operation_id>. If type is `rpc`, <path_to_grpc_proto_file>#<service_name>#<service_method>. If type is `graphql`, <url_to_graphql_endpoint>#<literal \"mutation\" or \"query\">#<query_or_mutation_name>. If type is `expression`, defines the workflow expression. | string | no |
 | type | Defines the function type. Is either `rest`, `rpc` or `expression`. Default is `rest` | enum | no |
 | [metadata](#Workflow-Metadata) | Metadata information. Can be used to define custom function information | object | no |
 
@@ -1758,6 +1905,8 @@ Depending on the function `type`, the `operation` property can be:
   For example `https://petstore.swagger.io/v2/swagger.json#getPetById`. 
 * If `type` is `rpc`, a combination of the gRPC proto document URI and the particular service name and service method name that needs to be invoked, separated by a '#'. 
 For example `file://myuserservice.proto#UserService#ListUsers`.
+* If `type` is `graphql`, a combination of the GraphQL schema definition URI and the particular service name and service method name that needs to be invoked, separated by a '#'. 
+For example `file://myuserservice.proto#UserService#ListUsers`.
 * If `type` is `expression`, defines the expression syntax. Take a look at the [workflow expressions section](#Workflow-Expressions) for more information on this.
 
 The [`metadata`](#Workflow-Metadata) property allows users to define custom information to function definitions.
@@ -2458,7 +2607,10 @@ it with its `object` type which has the following properties:
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
 | refName | Name of the referenced [function](#Function-Definition) | string | yes |
-| arguments | Arguments to be passed to the referenced function | object | no |
+| arguments | Arguments (inputs) to be passed to the referenced function | object | yes if function type is `graphql`, otherwise no |
+| selectionSet | Used if function type is `graphql`. String containing a valid GraphQL [selection set](https://spec.graphql.org/June2018/#sec-Selection-Sets) | string | yes if function type is `graphql`, otherwise no |
+
+tihomir
 
 <details><summary><strong>Click to view example definition</strong></summary>
 <p>
@@ -2496,15 +2648,18 @@ arguments:
 </details>
 
 The `refName` property is the name of the referenced [function](#Function-Definition).
+
 The `arguments` property defines the arguments that are to be passed to the referenced function.
-Values of the `arguments` property can be either static values, or an expression, for example:
+Here is an example of using the `arguments` property:
 
 ```json
 {
    "refName": "checkFundsAvailabe",
    "arguments": {
-     "account": "${ .accountId }",
-     "forAmount": "${.payment.amount }",
+     "account": {
+       "id": "${ .accountId }"
+     },
+     "forAmount": "${ .payment.amount }",
      "insufficientMessage": "The requested amount is not available."
    }
 }