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

yaml

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

json

{
  "action": "parse",
  "input": {"file_path": "/path/to/spec.yaml"}
}

Test Endpoints

json

{
  "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.