> For the complete documentation index, see [llms.txt](https://docs.a4b.vn/xflow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.a4b.vn/xflow/developer-guide/workflow-functions/rest.md).

# REST

The specification also supports describing REST invocations in the functions definition using [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object).

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}`:

{% code lineNumbers="true" %}

```json
{
  "functions":[
    {
      "name":"queryUserById",
      "operation": {
        "/users": {
          "get": {
            "parameters": [{
              "name": "id",
              "in": "path",
              "required": true 
            }]
          }
        }
      },
      "type":"rest"
    }
  ]
}
```

{% endcode %}

Note that the Function Definition's `operation` property must follow the [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object) specification definition.

The function can be referenced during workflow execution when the invocation of the REST service is desired. For example:

{% code lineNumbers="true" %}

```json
{
  "states":[
    {
      "name":"QueryUserInfo",
      "type":"operation",
      "actions":[
        {
          "functionRef":"queryUserById",
          "arguments":{
            "id":"${ .user.id }"
          }
        }
      ],
      "end":true
    }
  ]
}
```

{% endcode %}

Example of the `POST` request sending the state data as part of the body:

{% code lineNumbers="true" %}

```json
{
  "functions":[
    {
      "name": "createUser",
      "type": "rest",
      "operation": {
        "/users": {
          "post": {
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"                     
                      },
                      "email": {
                        "type": "string"
                      }
                    },
                    "required": ["name", "email"]
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}
```

{% endcode %}

Note that the `requestBody` [`content` attribute](https://spec.openapis.org/oas/v3.1.0#fixed-fields-10) is described inline rather than a reference to an external document.

You can reference the `createUser` function and filter the input data to invoke it. Given the workflow input data:

{% code lineNumbers="true" %}

```json
{
  "order":{
    "id":"1234N",
    "products":[
      {
        "name":"Product 1"
      }
    ]
  },
  "user":{
    "name":"John Doe",
    "email":"john@doe.com"
  }
}
```

{% endcode %}

Function invocation example:

{% code lineNumbers="true" %}

```json
{
  "states":[
    {
      "name":"CreateNewUser",
      "type":"operation",
      "actions":[
        {
          "functionRef":"createUser",
          "actionDataFilter":{
            "fromStateData":"${ .user }",
            "toStateData":"${ .user.id }"
          }
        }
      ],
      "end":true
    }
  ]
}
```

{% endcode %}

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:

{% code lineNumbers="true" %}

```json
{
  "order":{
    "id":"1234N",
    "products":[
      {
        "name":"Product 1"
      }
    ]
  },
  "user":{
    "id":"5678U",
    "name":"John Doe",
    "email":"john@doe.com"
  }
}
```

{% endcode %}

The specification does not support the [Security Requirement Object](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) since its redundat to function Auth Definition. If provided, this field is ignored.