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.