mirror of
https://github.com/simstudioai/sim.git
synced 2026-04-06 03:00:16 -04:00
43c0f5b199
* fix(api): add configurable request retries The API block docs described automatic retries, but the block didn't expose any retry controls and requests were executed only once. This adds tool-level retry support with exponential backoff (including Retry-After support) for timeouts, 429s, and 5xx responses, exposes retry settings in the API block and http_request tool, and updates the docs to match. Fixes #3225 * remove unnecessary helpers, cleanup * update desc * ack comments * ack comment * ack * handle timeouts --------- Co-authored-by: Jay Prajapati <79649559+jayy-77@users.noreply.github.com>
150 lines
4.0 KiB
Plaintext
150 lines
4.0 KiB
Plaintext
---
|
||
title: API
|
||
---
|
||
|
||
import { Callout } from 'fumadocs-ui/components/callout'
|
||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
|
||
import { Image } from '@/components/ui/image'
|
||
|
||
The API block connects your workflow to external services through HTTP requests. Supports GET, POST, PUT, DELETE, and PATCH methods for interacting with REST APIs.
|
||
|
||
<div className="flex justify-center">
|
||
<Image
|
||
src="/static/blocks/api.png"
|
||
alt="API Block"
|
||
width={500}
|
||
height={400}
|
||
className="my-6"
|
||
/>
|
||
</div>
|
||
|
||
## Configuration Options
|
||
|
||
### URL
|
||
|
||
The endpoint URL for the API request. This can be:
|
||
|
||
- A static URL entered directly in the block
|
||
- A dynamic URL connected from another block's output
|
||
- A URL with path parameters
|
||
|
||
### Method
|
||
|
||
Select the HTTP method for your request:
|
||
|
||
- **GET**: Retrieve data from the server
|
||
- **POST**: Send data to the server to create a resource
|
||
- **PUT**: Update an existing resource on the server
|
||
- **DELETE**: Remove a resource from the server
|
||
- **PATCH**: Partially update an existing resource
|
||
|
||
### Query Parameters
|
||
|
||
Define key-value pairs that will be appended to the URL as query parameters. For example:
|
||
|
||
```
|
||
Key: apiKey
|
||
Value: your_api_key_here
|
||
|
||
Key: limit
|
||
Value: 10
|
||
```
|
||
|
||
These would be added to the URL as `?apiKey=your_api_key_here&limit=10`.
|
||
|
||
### Headers
|
||
|
||
Configure HTTP headers for your request. Common headers include:
|
||
|
||
```
|
||
Key: Content-Type
|
||
Value: application/json
|
||
|
||
Key: Authorization
|
||
Value: Bearer your_token_here
|
||
```
|
||
|
||
### Request Body
|
||
|
||
For methods that support a request body (POST, PUT, PATCH), you can define the data to send. The body can be:
|
||
|
||
- JSON data entered directly in the block
|
||
- Data connected from another block's output
|
||
- Dynamically generated during workflow execution
|
||
|
||
### Accessing Results
|
||
|
||
After an API request completes, you can access its outputs:
|
||
|
||
- **`<api.data>`**: The response body data from the API
|
||
- **`<api.status>`**: HTTP status code (200, 404, 500, etc.)
|
||
- **`<api.headers>`**: Response headers from the server
|
||
- **`<api.error>`**: Error details if the request failed
|
||
|
||
## Advanced Features
|
||
|
||
### Dynamic URL Construction
|
||
|
||
Build URLs dynamically using variables from previous blocks:
|
||
|
||
```javascript
|
||
// In a Function block before the API
|
||
const userId = <start.userId>;
|
||
const apiUrl = `https://api.example.com/users/${userId}/profile`;
|
||
```
|
||
|
||
### Request Retries
|
||
|
||
The API block supports **configurable retries** (see the block’s **Advanced** settings):
|
||
|
||
- **Retries**: Number of retry attempts (additional tries after the first request)
|
||
- **Retry delay (ms)**: Initial delay before retrying (uses exponential backoff)
|
||
- **Max retry delay (ms)**: Maximum delay between retries
|
||
- **Retry non-idempotent methods**: Allow retries for **POST/PATCH** (may create duplicate requests)
|
||
|
||
Retries are attempted for:
|
||
|
||
- Network/connection failures and timeouts (with exponential backoff)
|
||
- Rate limits (**429**) and server errors (**5xx**)
|
||
|
||
### Response Validation
|
||
|
||
Validate API responses before processing:
|
||
|
||
```javascript
|
||
// In a Function block after the API
|
||
if (<api.status> === 200) {
|
||
const data = <api.data>;
|
||
// Process successful response
|
||
} else {
|
||
// Handle error response
|
||
console.error(`API Error: ${<api.status>}`);
|
||
}
|
||
```
|
||
|
||
## Outputs
|
||
|
||
- **`<api.data>`**: Response body data from the API
|
||
- **`<api.status>`**: HTTP status code
|
||
- **`<api.headers>`**: Response headers
|
||
- **`<api.error>`**: Error details if request failed
|
||
|
||
## Example Use Cases
|
||
|
||
**Fetch User Profile Data** - Retrieve user information from external service
|
||
```
|
||
Function (Build ID) → API (GET /users/{id}) → Function (Format) → Response
|
||
```
|
||
|
||
**Payment Processing** - Process payment through Stripe API
|
||
```
|
||
Function (Validate) → API (Stripe) → Condition (Success) → Supabase (Update)
|
||
```
|
||
|
||
## Best Practices
|
||
|
||
- **Use environment variables for sensitive data**: Don't hardcode API keys or credentials
|
||
- **Handle errors gracefully**: Connect error handling logic for failed requests
|
||
- **Validate responses**: Check status codes and response formats before processing data
|
||
- **Respect rate limits**: Be mindful of API rate limits and implement appropriate throttling
|