restapi

---
title: "REST API"
lang: "en-US"
draft: false
description: "Learn about how to set up a VDP REST API component https://github.com/instill-ai/instill-core"
---

The REST API component is a generic component that allows users to make requests to external REST APIs.
It can carry out the following tasks:
- [Get](#get)
- [Post](#post)
- [Patch](#patch)
- [Put](#put)
- [Delete](#delete)
- [Head](#head)
- [Options](#options)

## Release Stage

`Alpha`

## Configuration

The component definition and tasks are defined in the [definition.json](https://github.com/instill-ai/component/blob/main/generic/restapi/v0/config/definition.json) and [tasks.json](https://github.com/instill-ai/component/blob/main/generic/restapi/v0/config/tasks.json) files respectively.

## Setup


In order to communicate with the
external application, the following connection details need to be
provided. You may specify them directly in a pipeline recipe as key-value pairs
within the component's `setup` block, or you can create a **Connection** from
the [**Integration Settings**](https://www.instill.tech/docs/vdp/integration)
page and reference the whole `setup` as `setup:
${connection.<my-connection-id>}`.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| [Authentication](#authentication) (required) | `authentication` | object | Authentication method to use for the REST API  |

</div>


<details>
<summary>The <code>authentication</code> Object </summary>

<h4 id="setup-authentication">Authentication</h4>

`authentication` must fulfill one of the following schemas:

<h5 id="setup-no-auth"><code>No Auth</code></h5>

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| Auth Type | `auth-type` | string |  Must be `"NO_AUTH"`   |
</div>

<h5 id="setup-basic-auth"><code>Basic Auth</code></h5>

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| Auth Type | `auth-type` | string |  Must be `"BASIC_AUTH"`   |
| Password | `password` | string |  Password for Basic auth  |
| Username | `username` | string |  Username for Basic Auth  |
</div>

<h5 id="setup-api-key"><code>API Key</code></h5>

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| Auth Location | `auth-location` | string |  Add the API key to the header or query params.  <br/><details><summary><strong>Enum values</strong></summary><ul><li>`header`</li><li>`query`</li></ul></details>  |
| Auth Type | `auth-type` | string |  Must be `"API_KEY"`   |
| Key Name | `key` | string |  Key name for API key authentication  |
| Key Value | `value` | string |  Key value for API key authentication  |
</div>

<h5 id="setup-bearer-token"><code>Bearer Token</code></h5>

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Field | Field ID | Type | Note |
| :--- | :--- | :--- | :--- |
| Auth Type | `auth-type` | string |  Must be `"BEARER_TOKEN"`   |
| Token | `token` | string |  Bearer token  |
</div>
</details>

## Supported Tasks

### Get

Send a HTTP GET request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_GET` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `output-body-schema` | string | The request body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Post

Send a HTTP POST request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_POST` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `body` | any | The request body |
| Body | `output-body-schema` | string | The JSON schema of output body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Patch

Send a HTTP PATCH request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_PATCH` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `body` | any | The request body |
| Body | `output-body-schema` | string | The JSON schema of output body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Put

Send a HTTP PUT request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_PUT` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `body` | any | The request body |
| Body | `output-body-schema` | string | The JSON schema of output body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Delete

Send a HTTP DELETE request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_DELETE` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `body` | any | The request body |
| Body | `output-body-schema` | string | The JSON schema of output body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Head

Send a HTTP HEAD request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_HEAD` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `output-body-schema` | string | The request body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>

### Options

Send a HTTP OPTIONS request.

<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Input | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Task ID (required) | `task` | string | `TASK_OPTIONS` |
| Endpoint Url (required) | `endpoint-url` | string | The API endpoint url |
| Body | `body` | any | The request body |
| Body | `output-body-schema` | string | The JSON schema of output body |
</div>






<div class="markdown-col-no-wrap" data-col-1 data-col-2>

| Output | ID | Type | Description |
| :--- | :--- | :--- | :--- |
| Status Code | `status-code` | integer | The HTTP status code of the response |
| Body | `body` | any | The body of the response |
| Header | `header` | object | The HTTP header of the response |
</div>