API Specifications
API specs are YAML definitions for extracting data from REST APIs. They handle authentication, pagination, response processing, and incremental sync automatically.
When to Use
- Extract data from REST APIs (GET endpoints only)
- Build incremental sync workflows
- Handle complex pagination patterns
- Process nested JSON responses
- Chain multiple API calls with queues
Basic Structure
name: "My API"
description: "Data extraction from My API"
authentication:
type: "static"
headers:
Authorization: "Bearer {secrets.api_token}"
defaults:
state:
base_url: "https://api.example.com/v1"
request:
headers:
Accept: "application/json"
endpoints:
users:
description: "Fetch users"
request:
url: "{state.base_url}/users"
response:
records:
jmespath: "data[]"
primary_key: ["id"]
MCP Operations
Parse a Spec
{
"action": "parse",
"input": {"file_path": "/path/to/spec.yaml"}
}
Test Endpoints
{
"action": "test",
"input": {
"connection": "MY_API",
"endpoints": ["users"],
"debug": true,
"limit": 10
}
}
Topics Reference
This skill includes detailed documentation for each aspect of API specification building:
| Topic | Description |
|---|---|
| AUTHENTICATION.md | All 8 authentication types (static, basic, OAuth2, AWS, HMAC, sequence) |
| ENDPOINTS.md | Endpoint configuration, setup/teardown sequences |
| REQUEST.md | HTTP request configuration, rate limiting |
| PAGINATION.md | All pagination patterns (cursor, offset, page, link header) |
| RESPONSE.md | Record extraction, deduplication |
| PROCESSORS.md | Data transformations, aggregations |
| VARIABLES.md | Variable scopes, expressions, rendering order |
| QUEUES.md | Endpoint chaining, iteration |
| INCREMENTAL.md | Sync state, context variables |
| DYNAMIC.md | Runtime endpoint generation |
| FUNCTIONS.md | Expression functions reference |
| RULES.md | Response rules, retries, error handling |
Quick Reference
Authentication Types
| Type | Use Case |
|---|---|
static |
API key, Bearer token |
basic |
Username/password |
oauth2 |
OAuth 2.0 flows (client_credentials, authorization_code, device_code) |
aws-sigv4 |
AWS services |
hmac |
Crypto exchanges, custom signing |
sequence |
Multi-step custom auth |
Pagination Patterns
| Pattern | Example |
|---|---|
| Cursor | starting_after, page_token |
| Offset | offset + limit |
| Page | page number |
| Link header | GitHub-style rel="next" |
Variable Scopes
| Scope | Description |
|---|---|
secrets.* |
Credentials from connection |
state.* |
Endpoint state variables |
sync.* |
Persisted from previous run |
response.* |
HTTP response data |
record.* |
Current record in processor |
queue.* |
Endpoint chaining |
Full Documentation
See https://docs.slingdata.io/concepts/api-specs.md for complete reference.