Skip to content

Commit 90b4cdb

Browse files
ricardozaniniricardozanini
committed
Refactoring REST Operation to OpenAPI Path Item
Signed-off-by: Ricardo Zanini <[email protected]>
1 parent 9c5cb54 commit 90b4cdb

File tree

2 files changed

+90
-68
lines changed

2 files changed

+90
-68
lines changed

‎schema/functions.json

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,24 +35,23 @@
3535
"minLength": 1
3636
},
3737
"operation": {
38-
"type": "string",
39-
"description": "If type is `rest`, <path_to_openapi_definition>#<operation_id>. If type is `asyncapi`, <path_to_asyncapi_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 `odata`, <URI_to_odata_service>#<Entity_Set_Name>. If type is `expression`, defines the workflow expression. If type is `http`, <HTTP_method>#<request_target>",
40-
"minLength": 1
38+
"type": "object",
39+
"$ref": "#/definitions/operation"
4140
},
4241
"type": {
4342
"type": "string",
44-
"description": "Defines the function type. Is either `rest`, `http`,`asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `rest`",
43+
"description": "Defines the function type. Is either `rest`, `openapi`,`asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `openapi`.",
4544
"enum": [
4645
"rest",
47-
"http",
46+
"openapi",
4847
"asyncapi",
4948
"rpc",
5049
"graphql",
5150
"odata",
5251
"expression",
5352
"custom"
5453
],
55-
"default": "rest"
54+
"default": "openapi"
5655
},
5756
"authRef": {
5857
"oneOf": [
@@ -64,13 +63,13 @@
6463
{
6564
"type": "object",
6665
"description": "Configures both the auth definition used to retrieve the operation's resource and the auth definition used to invoke said operation",
67-
"properties":{
68-
"resource":{
66+
"properties": {
67+
"resource": {
6968
"type": "string",
7069
"description": "References an auth definition to be used to access the resource defined in the operation parameter",
7170
"minLength": 1
7271
},
73-
"invocation":{
72+
"invocation": {
7473
"type": "string",
7574
"description": "References an auth definition to be used to invoke the operation"
7675
}
@@ -91,6 +90,25 @@
9190
"name",
9291
"operation"
9392
]
93+
},
94+
"operation": {
95+
"oneOf": [
96+
{
97+
"type": "string",
98+
"description": "If type is `openapi`, <path_to_openapi_definition>#<operation_id>. If type is `asyncapi`, <path_to_asyncapi_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 `odata`, <URI_to_odata_service>#<Entity_Set_Name>. If type is `expression`, defines the workflow expression.",
99+
"minLength": 1
100+
},
101+
{
102+
"type": "object",
103+
"description": "OpenAPI Path Object definition",
104+
"$comment": "https://spec.openapis.org/oas/v3.1.0#paths-object",
105+
"patternProperties": {
106+
"^/": {
107+
"type": "object"
108+
}
109+
}
110+
}
111+
]
94112
}
95113
}
96114
}

‎specification.md

Lines changed: 63 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -992,8 +992,8 @@ They can be referenced by their domain-specific names inside workflow [states](#
992992

993993
Reference the following sections to learn more about workflow functions:
994994

995-
* [Using functions for OpenAPI RESTful service invocations](#using-functions-for-openapi-restful-service-invocations)
996-
+ [Using functions for HTTP Service Invocations](#using-functions-for-http-service-invocations)
995+
* [Using functions for OpenAPI Service invocations](#using-functions-for-openapi-service-invocations)
996+
+ [Using functions for RESTful Service Invocations](#using-functions-for-rest-service-invocations)
997997
* [Using functions for Async API Service Invocations](#Using-Functions-for-Async-API-Service-Invocations)
998998
* [Using functions for gRPC service invocation](#Using-Functions-For-RPC-Service-Invocations)
999999
* [Using functions for GraphQL service invocation](#Using-Functions-For-GraphQL-Service-Invocations)
@@ -1004,7 +1004,7 @@ Reference the following sections to learn more about workflow functions:
10041004
We can define if functions are invoked sync or async. Reference
10051005
the [functionRef](#FunctionRef-Definition) to learn more on how to do this.
10061006

1007-
#### Using Functions for OpenAPI RESTful Service Invocations
1007+
#### Using Functions for OpenAPI Service Invocations
10081008

10091009
[Functions](#Function-Definition) can be used to describe services and their operations that need to be invoked during
10101010
workflow execution. They can be referenced by states [action definitions](#Action-Definition) to clearly
@@ -1057,67 +1057,41 @@ For example:
10571057
}
10581058
```
10591059

1060-
Note that the referenced function definition type in this case must be `rest` (default type).
1060+
Note that the referenced function definition type in this case must be `openapi` (default type).
10611061

10621062
For more information about functions, reference the [Functions definitions](#Function-Definition) section.
10631063

1064-
#### Using functions for HTTP Service Invocations
1064+
#### Using functions for RESTful Service Invocations
10651065

1066-
The specification supports describing HTTP invocations via a simplified interface in the [functions definition](#Function-Definition).
1066+
The specification also supports describing REST invocations in the [functions definition](#Function-Definition) using [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object).
10671067

1068-
Here is an example function definition for HTTP requests with method `GET` and request target corresponding with [URI Template](https://www.rfc-editor.org/rfc/rfc6570.html) `/users/{id}`:
1068+
Here is an example function definition for REST requests with method `GET` and request target corresponding with [URI Template](https://www.rfc-editor.org/rfc/rfc6570.html) `/users/{id}`:
10691069

10701070
```json
10711071
{
10721072
"functions":[
10731073
{
10741074
"name":"queryUserById",
1075-
"operation":"GET#/users/{id}",
1076-
"type":"http"
1077-
}
1078-
]
1079-
}
1080-
```
1081-
1082-
Note that the [Function Definition](#Function-Definition)'s `operation` property must have the following format:
1083-
1084-
```text
1085-
<HTTP_method>#<request_target>
1086-
```
1087-
1088-
* The HTTP method used by the HTTP invocation. Can be any [valid HTTP method](https://www.rfc-editor.org/rfc/rfc9110.html#name-method-definitions) such as `GET`, `POST`, `PUT`, etc.
1089-
* The endpoint **location path** or the service full URL. Runtimes implementations are **discouraged** to expect the full URL in this field since this is a matter of infrastructure configuration.
1090-
1091-
The list below describes the HTTP function parameters in the `operation` attribute:
1092-
1093-
* Path parameters must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user/{id}`
1094-
* [Query parameters](https://www.rfc-editor.org/rfc/rfc9110.html#section-4.2.2) must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user?status={status}`.
1095-
1096-
<!-- TODO: refine how we are going to describe http headers parameters -->
1097-
Additional HTTP header fields can be passed via the `metadata` function definition. For example:
1098-
1099-
```json
1100-
{
1101-
"functions":[
1102-
{
1103-
"name":"queryUserById",
1104-
"operation":"GET#/users/{id}",
1105-
"type":"http",
1106-
"metadata":{
1107-
"x-custom-header":"the-value"
1108-
}
1075+
"operation": {
1076+
"/users": {
1077+
"get": {
1078+
"parameters": [{
1079+
"name": "id",
1080+
"in": "path",
1081+
"required": true
1082+
}]
1083+
}
1084+
}
1085+
},
1086+
"type":"rest"
11091087
}
11101088
]
11111089
}
11121090
```
11131091

1114-
> Since the data manipulated in the Serverless Workflow specification is primarly JSON, runtimes are encouraged to support at least `Content-Type: application/json` header field for HTTP requests.
1115-
1116-
Avoid passing sensitive information in headers such as authentication tokens. See the [auth definition](#auth-definition) for more information.
1092+
Note that the [Function Definition](#Function-Definition)'s `operation` property must follow the OpenAPI Paths Object specification definition.
11171093

1118-
HTTP request content doesn't need to be described in the function definition. **All the data within the state** should be passed to the HTTP request. See the [action data filter](#action-data-filters) if you need to limit the amount of data passed to a given action.
1119-
1120-
The function can be referenced during workflow execution when the invocation of the HTTP service is desired. For example:
1094+
The function can be referenced during workflow execution when the invocation of the REST service is desired. For example:
11211095

11221096
```json
11231097
{
@@ -1145,17 +1119,43 @@ Example of the `POST` request sending the state data as part of the body:
11451119
{
11461120
"functions":[
11471121
{
1148-
"name":"createUser",
1149-
"operation":"POST#/users",
1150-
"type":"http"
1122+
"name": "createUser",
1123+
"operation": {
1124+
"/users": {
1125+
"post": {
1126+
"requestBody": {
1127+
"content": {
1128+
"application/json": {
1129+
"schema": {
1130+
"type": "object",
1131+
"properties": {
1132+
"id": {
1133+
"type": "string"
1134+
},
1135+
"name": {
1136+
"type": "string"
1137+
},
1138+
"email": {
1139+
"type": "string"
1140+
}
1141+
},
1142+
"required": ["name", "email"]
1143+
}
1144+
}
1145+
}
1146+
}
1147+
}
1148+
}
1149+
},
1150+
"type": "rest"
11511151
}
11521152
]
11531153
}
11541154
```
11551155

1156-
Then you can reference the `createUser` function and filter the input data to invoke it.
1156+
Note that the `requestBody` content schema is described inline rather than a reference to an external document.
11571157

1158-
Input data example:
1158+
You can reference the `createUser` function and filter the input data to invoke it, as shown in the example below:
11591159

11601160
```json
11611161
{
@@ -1197,7 +1197,7 @@ Function invocation example:
11971197
}
11981198
```
11991199

1200-
In this case, only the contents of the `user` attribute will be passed to the function. The user ID returned by the HTTP request body will then be added to the state data:
1200+
In this case, only the contents of the `user` attribute will be passed to the function. The user ID returned by the REST request body will then be added to the state data:
12011201

12021202
```json
12031203
{
@@ -1217,6 +1217,8 @@ In this case, only the contents of the `user` attribute will be passed to the fu
12171217
}
12181218
```
12191219

1220+
The specification does not support the [Security Requirement Object](https://spec.openapis.org/oas/v3.1.0#security-requirement-object). To define authentication for the REST operation, use the [Auth Definition](#Auth-Definition). If provided, this field is ignored.
1221+
12201222
#### Using Functions for Async API Service Invocations
12211223

12221224
[Functions](#Function-Definition) can be used to invoke PUBLISH and SUBSCRIBE operations on a message broker documented by the [Async API Specification](https://www.asyncapi.com/docs/specifications/v2.1.0).
@@ -3347,17 +3349,17 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that
33473349
| Parameter | Description | Type | Required |
33483350
| --- | --- | --- | --- |
33493351
| name | Unique function name | string | yes |
3350-
| operation | See the table "Function Operation description by type" below. | string | yes |
3351-
| type | Defines the function type. Can be either `rest`, `http`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `rest` | enum | no |
3352+
| operation | See the table "Function Operation description by type" below. | string or object | yes |
3353+
| type | Defines the function type. Can be either `rest`, `openapi`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `openapi` | enum | no |
33523354
| authRef | References an [auth definition](#Auth-Definition) name to be used to access to resource defined in the operation parameter | string | no |
33533355
| [metadata](#Workflow-Metadata) | Metadata information. Can be used to define custom function information | object | no |
33543356

33553357
Function Operation description by type:
33563358

33573359
| Type | Operation Description |
33583360
| ---- | --------- |
3359-
| `rest` | <path_to_openapi_definition>#<operation_id> |
3360-
| `http` | <HTTP_method>#<request_target> |
3361+
| `openapi` | <path_to_openapi_definition>#<operation_id> |
3362+
| `rest` | [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object) definition |
33613363
| `asyncapi` | <path_to_asyncapi_definition>#<operation_id> |
33623364
| `rpc` | <path_to_grpc_proto_file>#<service_name>#<service_method> |
33633365
| `graphql` | <url_to_graphql_endpoint>#<literal \"mutation\" or \"query\">#<query_or_mutation_name> |
@@ -3399,12 +3401,14 @@ operation: https://hellworldservice.api.com/api.json#helloWorld
33993401

34003402
The `name` property defines an unique name of the function definition.
34013403

3402-
The `type` property defines the function type. Its value can be either `rest` or `expression`. Default value is `rest`.
3404+
The `type` property defines the function type. Its value can be either `rest`, `openapi` or `expression`. Default value is `openapi`.
34033405

34043406
Depending on the function `type`, the `operation` property can be:
34053407

3406-
* If `type` is `rest`, a combination of the function/service OpenAPI definition document URI and the particular service operation that needs to be invoked, separated by a '#'.
3408+
* If `type` is `openapi`, a combination of the function/service OpenAPI definition document URI and the particular service operation that needs to be invoked, separated by a '#'.
34073409
For example `https://petstore.swagger.io/v2/swagger.json#getPetById`.
3410+
* If `type` is `rest`, an object definition of the [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object).
3411+
For example, see [Using Functions for RESTful Service Invocations](#using-functions-for-rest-service-invocations).
34083412
* If `type` is `asyncapi`, a combination of the AsyncApi definition document URI and the particular service operation that needs to be invoked, separated by a '#'.
34093413
For example `file://streetlightsapi.yaml#onLightMeasured`.
34103414
* 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 '#'.

0 commit comments

Comments
 (0)