HTTP & API Operations 🟡 BETA

This section covers keywords for making HTTP requests and integrating with external APIs. These keywords enable bots to communicate with REST APIs, GraphQL endpoints, SOAP services, and any HTTP-based web service.

Overview

General Bots provides a complete set of HTTP keywords for API integration:

Quick Examples

REST API Call

' GET request
data = GET "https://api.example.com/users/123"
TALK "User name: " + data.name

' POST request
result = POST "https://api.example.com/users" WITH
    name = "John",
    email = "john@example.com"
TALK "Created user ID: " + result.id

' PUT request (full update)
PUT "https://api.example.com/users/123" WITH
    name = "John Doe",
    email = "johndoe@example.com",
    status = "active"

' PATCH request (partial update)
PATCH "https://api.example.com/users/123" WITH status = "inactive"

' DELETE request
DELETE HTTP "https://api.example.com/users/123"

With Authentication

' Set authorization header
SET HEADER "Authorization", "Bearer " + api_token
SET HEADER "Content-Type", "application/json"

' Make authenticated request
result = GET "https://api.example.com/protected/resource"

' Clear headers when done
SET HEADER "Authorization", ""

GraphQL Query

query = '
    query GetUser($id: ID!) {
        user(id: $id) {
            name
            email
            orders { id total }
        }
    }
'

result = GRAPHQL "https://api.example.com/graphql", query WITH id = "123"
TALK "User: " + result.data.user.name

SOAP Service

' Call a SOAP web service
request = '
    <GetWeather xmlns="http://weather.example.com">
        <City>New York</City>
    </GetWeather>
'

result = SOAP "https://weather.example.com/service", "GetWeather", request
TALK "Temperature: " + result.Temperature

Common Patterns

API Client Setup

' Configure API base URL and authentication
api_base = "https://api.myservice.com/v1"
SET HEADER "Authorization", "Bearer " + GET BOT MEMORY "api_token"
SET HEADER "X-API-Version", "2025-01"

' Helper function pattern
' GET users
users = GET api_base + "/users"

' GET specific user
user = GET api_base + "/users/" + user_id

' CREATE user
new_user = POST api_base + "/users", user_data

' UPDATE user
PUT api_base + "/users/" + user_id, updated_data

' DELETE user
DELETE HTTP api_base + "/users/" + user_id

Error Handling

ON ERROR RESUME NEXT

result = POST "https://api.example.com/orders", order_data

IF ERROR THEN
    PRINT "API Error: " + ERROR_MESSAGE
    TALK "Sorry, I couldn't process your order. Please try again."
ELSE IF result.error THEN
    TALK "Order failed: " + result.error.message
ELSE
    TALK "Order placed! ID: " + result.id
END IF

Retry Logic

max_retries = 3
retry_count = 0
success = false

WHILE retry_count < max_retries AND NOT success
    ON ERROR RESUME NEXT
    result = POST api_url, data
    
    IF NOT ERROR AND NOT result.error THEN
        success = true
    ELSE
        retry_count = retry_count + 1
        WAIT 2  ' Wait 2 seconds before retry
    END IF
WEND

IF success THEN
    TALK "Request successful!"
ELSE
    TALK "Request failed after " + max_retries + " attempts."
END IF

Pagination

' Fetch all pages of results
all_items = []
page = 1
has_more = true

WHILE has_more
    result = GET api_base + "/items?page=" + page + "&limit=100"
    
    FOR EACH item IN result.items
        all_items = APPEND(all_items, item)
    NEXT
    
    has_more = result.has_more
    page = page + 1
WEND

TALK "Fetched " + LEN(all_items) + " total items"

Request Headers

Common headers you might need to set:

SET HEADER "Authorization", "Bearer " + token
SET HEADER "Content-Type", "application/json"
SET HEADER "Accept", "application/json"
SET HEADER "X-Request-ID", GUID()

Response Handling

JSON Responses

Most APIs return JSON, automatically parsed:

result = GET "https://api.example.com/user"

' Access properties directly
TALK "Name: " + result.name
TALK "Email: " + result.email

' Access nested objects
TALK "City: " + result.address.city

' Access arrays
FOR EACH order IN result.orders
    TALK "Order: " + order.id
NEXT

Check Response Status

result = POST api_url, data

IF result.status = 201 THEN
    TALK "Resource created!"
ELSE IF result.status = 400 THEN
    TALK "Bad request: " + result.error.message
ELSE IF result.status = 401 THEN
    TALK "Authentication failed. Please log in again."
ELSE IF result.status = 404 THEN
    TALK "Resource not found."
ELSE IF result.status >= 500 THEN
    TALK "Server error. Please try again later."
END IF

Configuration

Configure HTTP settings in config.csv:

name,value
http-timeout,30
http-retry-count,3
http-retry-delay,1000
http-base-url,https://api.mycompany.com
http-user-agent,GeneralBots/1.0
http-max-redirects,10
http-verify-ssl,true

Security Best Practices

1. Store credentials securely — Use Vault or environment variables for API keys
2. Use HTTPS — Never send credentials over unencrypted connections
3. Validate responses — Check status codes and handle errors
4. Set timeouts — Prevent hanging on slow APIs
5. Rate limit — Respect API rate limits to avoid being blocked
6. Log requests — Enable logging for debugging without exposing secrets

' Good: Token from secure storage
token = GET BOT MEMORY "api_token"
SET HEADER "Authorization", "Bearer " + token

' Bad: Hardcoded token
' SET HEADER "Authorization", "Bearer sk-abc123"  ' NEVER DO THIS

See Also

• GET — Retrieve data
• POST — Create resources
• PUT — Update resources
• PATCH — Partial updates
• DELETE HTTP — Delete resources
• SET HEADER — Set request headers
• GRAPHQL — GraphQL operations
• SOAP — SOAP web services