diff --git a/ctk/features/call.feature b/ctk/features/call.feature index 311d8f8c..5e9cbb8a 100644 --- a/ctk/features/call.feature +++ b/ctk/features/call.feature @@ -62,6 +62,48 @@ Feature: Call Task And the workflow output should have properties 'request', 'request.method', 'request.uri', 'request.headers', 'headers', 'statusCode', 'content' And the workflow output should have properties 'content.id', 'content.name', 'content.status' + # Tests HTTP call using `response` output with output filtering + # Tests accessing response headers and content via output.as + Scenario: Call HTTP With Response Output And Output Filtering + Given a workflow with definition: + """yaml + document: + dsl: '1.0.3' + namespace: default + name: http-call-response-filtering + version: '1.0.0' + do: + - getPet: + call: http + with: + method: get + endpoint: + uri: https://petstore.swagger.io/v2/pet/{petId} + output: response + output: + as: + pet: ${ .content } + headers: ${ .headers } + hasHeaders: ${ (.headers | length) > 0 } + statusCode: ${ .statusCode } + """ + And given the workflow input is: + """yaml + petId: 1 + """ + When the workflow is executed + Then the workflow should complete + And the workflow output should have properties 'pet', 'headers', 'hasHeaders', 'statusCode' + And the workflow output should have properties 'pet.id', 'pet.name', 'pet.status' + And the workflow output should have a 'statusCode' property with value: + """yaml + 200 + """ + And the workflow output should have a 'hasHeaders' property with value: + """yaml + true + """ + # Tests HTTP call using `basic` authentication # Tests interpolated path parameters Scenario: Call HTTP Using Basic Authentication diff --git a/dsl-reference.md b/dsl-reference.md index 8237aa66..74a8a9b5 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -441,6 +441,7 @@ The [HTTP Call](#http-call) enables workflows to interact with external services ###### Examples +*Basic HTTP GET call:* ```yaml document: dsl: '1.0.4' @@ -455,6 +456,27 @@ do: endpoint: https://petstore.swagger.io/v2/pet/{petId} ``` +*Accessing HTTP response headers and content:* +```yaml +document: + dsl: '1.0.4' + namespace: test + name: http-response-example + version: '0.1.0' +do: + - getPet: + call: http + with: + method: get + endpoint: https://petstore.swagger.io/v2/pet/{petId} + output: response + output: + as: + pet: ${ .content } + headers: ${ .headers } + statusCode: ${ .statusCode } +``` + ##### OpenAPI Call The [OpenAPI Call](#openapi-call) enables workflows to interact with external services described by [OpenAPI](https://www.openapis.org). @@ -2419,17 +2441,22 @@ Describes an enpoint. ### HTTP Response -Describes an HTTP response. +Describes an HTTP response conforming to [RFC 9110 (HTTP Semantics)](https://www.rfc-editor.org/rfc/rfc9110.html). #### Properties | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| | request | [`request`](#http-request) | `yes` | The HTTP request associated with the HTTP response. | -| statusCode | `integer` | `yes` | The HTTP response status code. | +| statusCode | `integer` | `yes` | The 3-digit numeric HTTP status code (e.g., `200`, `404`) parsed from the HTTP response status line ([RFC 9112 Section 3.1](https://www.rfc-editor.org/rfc/rfc9112.html#section-3.1)) or the `:status` pseudo-header field ([RFC 9113](https://www.rfc-editor.org/rfc/rfc9113.html)). | | headers | `map[string, string]` | `no` | The HTTP response headers, if any. | | content | `any` | `no` | The HTTP response content, if any.
*If the request's content type is one of the following, should contain the deserialized response content. Otherwise, should contain the base-64 encoded response content, if any.*| +> [!NOTE] +> In HTTP/1.1 ([RFC 9112](https://www.rfc-editor.org/rfc/rfc9112.html)), the response status line is defined as `HTTP-version status-code [reason-phrase]` (e.g., `HTTP/1.1 200 OK`). In HTTP/2 ([RFC 9113](https://www.rfc-editor.org/rfc/rfc9113.html)) and HTTP/3 ([RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html)), status codes are carried in the `:status` pseudo-header and reason phrases are omitted. Runtimes map the status code to `statusCode` as an integer. +> +> When `output: response` is specified on an [HTTP call](#http-call) or [OpenAPI call](#openapi-call), the task produces this structure as its raw output (`.`). Authors can then access response headers, status code, or content using runtime expressions in `output.as` or `export.as` (for example, `${ .headers }`, `${ .statusCode }`, or `${ .content }`). + #### Examples ```yaml diff --git a/examples/call-http-output-headers.yaml b/examples/call-http-output-headers.yaml new file mode 100644 index 00000000..8965cf3f --- /dev/null +++ b/examples/call-http-output-headers.yaml @@ -0,0 +1,28 @@ +# yaml-language-server: $schema=../schema/workflow.yaml +document: + dsl: '1.0.4' + namespace: examples + name: http-output-headers + version: '1.0.0' +input: + schema: + format: json + document: + type: object + required: + - petId + properties: + petId: + type: integer +do: + - getPet: + call: http + with: + method: get + endpoint: https://petstore.swagger.io/v2/pet/{petId} + output: response + output: + as: + pet: ${ .content } + headers: ${ .headers } + statusCode: ${ .statusCode }