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.
1---2name: sling-api-specs3description: Build REST API specifications for Sling data extraction. Use when creating API specs, configuring authentication (OAuth, API key, Bearer token, HMAC), setting up pagination (cursor, offset, page), processing responses, handling rate limits, chaining endpoints with queues, or implementing incremental sync.4---5
6# API Specifications
7
8API specs are YAML definitions for extracting data from REST APIs. They handle authentication, pagination, response processing, and incremental sync automatically.
9
10## When to Use
11
12- Extract data from REST APIs (GET endpoints only)
13- Build incremental sync workflows
14- Handle complex pagination patterns
15- Process nested JSON responses
16- Chain multiple API calls with queues
17
18## Basic Structure
19
20```yaml
21name: "My API"
22description: "Data extraction from My API"
23
24authentication:
25 type: "static"
26 headers:
27 Authorization: "Bearer {secrets.api_token}"
28
29defaults:
30 state:
31 base_url: "https://api.example.com/v1"
32 request:
33 headers:
34 Accept: "application/json"
35
36endpoints:
37 users:
38 description: "Fetch users"
39 request:
40 url: "{state.base_url}/users"
41 response:
42 records:
43 jmespath: "data[]"
44 primary_key: ["id"]
45```
46
47## MCP Operations
48
49### Parse a Spec
50```json
51{
52 "action": "parse",
53 "input": {"file_path": "/path/to/spec.yaml"}
54}
55```
56
57### Test Endpoints
58```json
59{
60 "action": "test",
61 "input": {
62 "connection": "MY_API",
63 "endpoints": ["users"],
64 "debug": true,
65 "limit": 10
66 }
67}
68```
69
70## Topics Reference
71
72This skill includes detailed documentation for each aspect of API specification building:
73
74| Topic | Description |
75|-------|-------------|
76| [AUTHENTICATION.md](AUTHENTICATION.md) | All 8 authentication types (static, basic, OAuth2, AWS, HMAC, sequence) |
77| [ENDPOINTS.md](ENDPOINTS.md) | Endpoint configuration, setup/teardown sequences |
78| [REQUEST.md](REQUEST.md) | HTTP request configuration, rate limiting |
79| [PAGINATION.md](PAGINATION.md) | All pagination patterns (cursor, offset, page, link header) |
80| [RESPONSE.md](RESPONSE.md) | Record extraction, deduplication |
81| [PROCESSORS.md](PROCESSORS.md) | Data transformations, aggregations |
82| [VARIABLES.md](VARIABLES.md) | Variable scopes, expressions, rendering order |
83| [QUEUES.md](QUEUES.md) | Endpoint chaining, iteration |
84| [INCREMENTAL.md](INCREMENTAL.md) | Sync state, context variables |
85| [DYNAMIC.md](DYNAMIC.md) | Runtime endpoint generation |
86| [FUNCTIONS.md](FUNCTIONS.md) | Expression functions reference |
87| [RULES.md](RULES.md) | Response rules, retries, error handling |
88
89## Quick Reference
90
91### Authentication Types
92
93| Type | Use Case |
94|------|----------|
95| `static` | API key, Bearer token |
96| `basic` | Username/password |
97| `oauth2` | OAuth 2.0 flows (client_credentials, authorization_code, device_code) |
98| `aws-sigv4` | AWS services |
99| `hmac` | Crypto exchanges, custom signing |
100| `sequence` | Multi-step custom auth |
101
102### Pagination Patterns
103
104| Pattern | Example |
105|---------|---------|
106| Cursor | `starting_after`, `page_token` |
107| Offset | `offset` + `limit` |
108| Page | `page` number |
109| Link header | GitHub-style `rel="next"` |
110
111### Variable Scopes
112
113| Scope | Description |
114|-------|-------------|
115| `secrets.*` | Credentials from connection |
116| `state.*` | Endpoint state variables |
117| `sync.*` | Persisted from previous run |
118| `response.*` | HTTP response data |
119| `record.*` | Current record in processor |
120| `queue.*` | Endpoint chaining |
121
122## Full Documentation
123
124See https://docs.slingdata.io/concepts/api-specs.md for complete reference.
modbender