Mastering API Integration with n8n: From REST to GraphQL

Introduction: API Integration in the Modern Stack#

APIs are the backbone of modern software architecture, enabling systems to communicate and share data seamlessly. n8n excels at API integration, providing powerful tools to connect, transform, and orchestrate data flows between any services. This comprehensive guide explores advanced API integration patterns using n8n.

Understanding n8n’s API Capabilities#

Core API Features#

HTTP Request Node: Universal API connector
Webhook Node: Receive real-time data
GraphQL Node: Query GraphQL endpoints
Custom Authentication: OAuth2, API Key, Bearer Token
Response Handling: JSON, XML, Binary data
Rate Limiting: Built-in throttling mechanisms

REST API Integration Patterns#

Example 1: Multi-Service Data Aggregation#

Scenario: Aggregate user data from multiple services (CRM, Support, Analytics) into a unified profile.

1
{
2
  "name": "User Profile Aggregation",
3
  "nodes": [
4
    {
5
      "name": "Trigger",
6
      "type": "n8n-nodes-base.webhook",
7
      "parameters": {
8
        "path": "user-profile",
9
        "responseMode": "onReceived",
10
        "responseData": "allEntries"
11
      }
12
    },
13
    {
14
      "name": "Get CRM Data",
15
      "type": "n8n-nodes-base.httpRequest",
16
      "parameters": {
17
        "url": "https://api.crm.com/v2/contacts/{{$json.userId}}",
18
        "method": "GET",
19
        "authentication": "predefinedCredentialType",
20
        "nodeCredentialType": "hubspotApi",
21
        "options": {
22
          "timeout": 10000,
23
          "retry": {
24
            "maxTries": 3,
25
            "waitBetweenTries": 1000
26
          }
27
        }
28
      }
29
    },
30
    {
31
      "name": "Get Support Tickets",
32
      "type": "n8n-nodes-base.httpRequest",
33
      "parameters": {
34
        "url": "https://api.support.com/tickets",
35
        "method": "GET",
36
        "queryParameters": {
37
          "parameters": [
38
            {
39
              "name": "customer_id",
40
              "value": "={{$json.userId}}"
41
            },
42
            {
43
              "name": "status",
44
              "value": "all"
45
            }
46
          ]
47
        },
48
        "headerParameters": {
49
          "parameters": [
50
            {
51
              "name": "Authorization",
52
              "value": "Bearer {{$credentials.supportApiToken}}"
53
            }
54
          ]
55
        }
56
      }
57
    },
58
    {
59
      "name": "Get Analytics Data",
60
      "type": "n8n-nodes-base.httpRequest",
61
      "parameters": {
62
        "url": "https://analytics.api.com/user-metrics",
63
        "method": "POST",
64
        "bodyParameters": {
65
          "parameters": [
66
            {
67
              "name": "userId",
68
              "value": "={{$json.userId}}"
69
            },
70
            {
71
              "name": "metrics",
72
              "value": ["engagement", "activity", "conversion"]
73
            },
74
            {
75
              "name": "dateRange",
76
              "value": {
77
                "start": "={{$now.minus(30, 'days').toISO()}}",
78
                "end": "={{$now.toISO()}}"
79
              }
80
            }
81
          ]
82
        }
83
      }
84
    },
85
    {
86
      "name": "Merge Data",
87
      "type": "n8n-nodes-base.function",
88
      "parameters": {
89
        "functionCode": `
90
          const crmData = $items[0].json;
91
          const supportData = $items[1].json;
92
          const analyticsData = $items[2].json;
93

94
          const unifiedProfile = {
95
            userId: crmData.id,
96
            profile: {
97
              name: crmData.name,
98
              email: crmData.email,
99
              company: crmData.company,
100
              created: crmData.createdAt
101
            },
102
            support: {
103
              totalTickets: supportData.total,
104
              openTickets: supportData.open,
105
              avgResponseTime: supportData.avgResponseTime,
106
              satisfaction: supportData.satisfaction
107
            },
108
            analytics: {
109
              lastActive: analyticsData.lastSeen,
110
              totalSessions: analyticsData.sessions,
111
              engagementScore: analyticsData.engagement,
112
              lifetime_value: analyticsData.ltv
113
            },
114
            aggregatedAt: new Date().toISOString()
115
          };
116

117
          return [{json: unifiedProfile}];
118
        `
119
      }
120
    }
121
  ]
122
}

Example 2: OAuth2 Authentication Flow#

Scenario: Implement OAuth2 authentication for Spotify API integration.

1
// OAuth2 Configuration and Token Management
2
const oauth2Integration = {
3
  name: "Spotify OAuth2 Integration",
4

5
  // Initial Authorization
6
  authorization: {
7
    type: "n8n-nodes-base.httpRequest",
8
    parameters: {
9
      url: "https://accounts.spotify.com/authorize",
10
      method: "GET",
11
      queryParameters: {
12
        client_id: "{{$credentials.spotifyClientId}}",
13
        response_type: "code",
14
        redirect_uri: "{{$env.N8N_WEBHOOK_URL}}/webhook/spotify-callback",
15
        scope: "user-read-private user-read-email playlist-modify-public",
16
        state: "{{$json.sessionId}}"
17
      }
18
    }
19
  },
20

21
  // Token Exchange
22
  tokenExchange: {
23
    type: "n8n-nodes-base.httpRequest",
24
    parameters: {
25
      url: "https://accounts.spotify.com/api/token",
26
      method: "POST",
27
      authentication: "basicAuth",
28
      nodeCredentialType: "spotifyOAuth2Api",
29
      bodyParameters: {
30
        grant_type: "authorization_code",
31
        code: "{{$json.authorizationCode}}",
32
        redirect_uri: "{{$env.N8N_WEBHOOK_URL}}/webhook/spotify-callback"
33
      }
34
    }
35
  },
36

37
  // Token Refresh Logic
38
  tokenRefresh: {
39
    type: "n8n-nodes-base.function",
40
    code: `
41
      const tokenData = await $getWorkflowStaticData('spotify_token');
42

43
      if (!tokenData || !tokenData.refresh_token) {
44
        throw new Error('No refresh token available');
45
      }
46

47
      // Check if token is expired
48
      const tokenExpiry = new Date(tokenData.expires_at);
49
      const now = new Date();
50

51
      if (tokenExpiry > now) {
52
        // Token still valid
53
        return [{json: {
54
          access_token: tokenData.access_token,
55
          valid: true
56
        }}];
57
      }
58

59
      // Refresh the token
60
      const response = await $http.post('https://accounts.spotify.com/api/token', {
61
        body: {
62
          grant_type: 'refresh_token',
63
          refresh_token: tokenData.refresh_token
64
        },
65
        headers: {
66
          'Authorization': 'Basic ' + Buffer.from(
67
            $credentials.clientId + ':' + $credentials.clientSecret
68
          ).toString('base64')
69
        }
70
      });
71

72
      // Store new token
73
      const newTokenData = {
74
        access_token: response.data.access_token,
75
        refresh_token: response.data.refresh_token || tokenData.refresh_token,
76
        expires_at: new Date(Date.now() + response.data.expires_in * 1000).toISOString()
77
      };
78

79
      await $setWorkflowStaticData('spotify_token', newTokenData);
80

81
      return [{json: {
82
        access_token: newTokenData.access_token,
83
        valid: true,
84
        refreshed: true
85
      }}];
86
    `
87
  }
88
};

GraphQL Integration#

Example 3: GitHub GraphQL API Integration#

Scenario: Query GitHub GraphQL API to fetch repository information and create automated reports.

1
// GitHub GraphQL Integration
2
const githubGraphQL = {
3
  name: "GitHub Repository Analytics",
4

5
  nodes: [
6
    {
7
      name: "GraphQL Query",
8
      type: "n8n-nodes-base.graphql",
9
      parameters: {
10
        endpoint: "https://api.github.com/graphql",
11
        requestFormat: "graphql",
12
        query: `
13
          query RepositoryInfo($owner: String!, $name: String!) {
14
            repository(owner: $owner, name: $name) {
15
              name
16
              description
17
              stargazerCount
18
              forkCount
19
              issues(states: OPEN) {
20
                totalCount
21
              }
22
              pullRequests(states: OPEN) {
23
                totalCount
24
              }
25
              releases(last: 5) {
26
                nodes {
27
                  tagName
28
                  publishedAt
29
                  url
30
                }
31
              }
32
              languages(first: 10) {
33
                edges {
34
                  node {
35
                    name
36
                    color
37
                  }
38
                  size
39
                }
40
                totalSize
41
              }
42
              collaborators {
43
                totalCount
44
              }
45
            }
46
          }
47
        `,
48
        variables: {
49
          owner: "{{$json.repoOwner}}",
50
          name: "{{$json.repoName}}"
51
        },
52
        headerParameters: {
53
          Authorization: "Bearer {{$credentials.githubToken}}"
54
        }
55
      }
56
    },
57
    {
58
      name: "Process Repository Data",
59
      type: "n8n-nodes-base.function",
60
      parameters: {
61
        functionCode: `
62
          const repo = $input.item.json.data.repository;
63

64
          // Calculate language percentages
65
          const totalSize = repo.languages.totalSize;
66
          const languages = repo.languages.edges.map(edge => ({
67
            name: edge.node.name,
68
            percentage: ((edge.size / totalSize) * 100).toFixed(2),
69
            color: edge.node.color
70
          }));
71

72
          // Format release data
73
          const releases = repo.releases.nodes.map(release => ({
74
            version: release.tagName,
75
            date: new Date(release.publishedAt).toLocaleDateString(),
76
            url: release.url
77
          }));
78

79
          // Create summary report
80
          const report = {
81
            repository: {
82
              name: repo.name,
83
              description: repo.description
84
            },
85
            metrics: {
86
              stars: repo.stargazerCount,
87
              forks: repo.forkCount,
88
              openIssues: repo.issues.totalCount,
89
              openPRs: repo.pullRequests.totalCount,
90
              contributors: repo.collaborators.totalCount
91
            },
92
            languages: languages,
93
            recentReleases: releases,
94
            generatedAt: new Date().toISOString()
95
          };
96

97
          return [{json: report}];
98
        `
99
      }
100
    }
101
  ]
102
};

Example 4: Complex GraphQL Mutations#

Scenario: Create and manage content in a headless CMS using GraphQL mutations.

1
{
2
  "name": "CMS Content Management",
3
  "nodes": [
4
    {
5
      "name": "Create Article",
6
      "type": "n8n-nodes-base.graphql",
7
      "parameters": {
8
        "endpoint": "https://cms.api.com/graphql",
9
        "requestFormat": "graphql",
10
        "query": `
11
          mutation CreateArticle($input: ArticleInput!) {
12
            createArticle(input: $input) {
13
              id
14
              slug
15
              title
16
              status
17
              publishedAt
18
              author {
19
                id
20
                name
21
              }
22
            }
23
          }
24
        `,
25
        "variables": {
26
          "input": {
27
            "title": "{{$json.title}}",
28
            "content": "{{$json.content}}",
29
            "excerpt": "{{$json.excerpt}}",
30
            "authorId": "{{$json.authorId}}",
31
            "categoryIds": "{{$json.categories}}",
32
            "tags": "{{$json.tags}}",
33
            "seo": {
34
              "metaTitle": "{{$json.seo.title}}",
35
              "metaDescription": "{{$json.seo.description}}",
36
              "keywords": "{{$json.seo.keywords}}"
37
            },
38
            "status": "DRAFT"
39
          }
40
        }
41
      }
42
    },
43
    {
44
      "name": "Upload Media",
45
      "type": "n8n-nodes-base.graphql",
46
      "parameters": {
47
        "query": `
48
          mutation UploadMedia($file: Upload!, $articleId: ID!) {
49
            uploadMedia(file: $file, articleId: $articleId) {
50
              id
51
              url
52
              mimeType
53
              size
54
            }
55
          }
56
        `,
57
        "variables": {
58
          "file": "{{$binary.data}}",
59
          "articleId": "{{$json.id}}"
60
        }
61
      }
62
    },
63
    {
64
      "name": "Publish Article",
65
      "type": "n8n-nodes-base.graphql",
66
      "parameters": {
67
        "query": `
68
          mutation PublishArticle($id: ID!) {
69
            updateArticle(id: $id, input: { status: PUBLISHED }) {
70
              id
71
              status
72
              publishedAt
73
              url
74
            }
75
          }
76
        `,
77
        "variables": {
78
          "id": "{{$json.id}}"
79
        }
80
      }
81
    }
82
  ]
83
}

Webhook Integration Patterns#

Example 5: Multi-Provider Webhook Handler#

Scenario: Handle webhooks from multiple providers with different formats and authentication methods.

1
// Universal Webhook Handler
2
const webhookHandler = {
3
  name: "Multi-Provider Webhook Router",
4

5
  // Main webhook receiver
6
  receiver: {
7
    type: "n8n-nodes-base.webhook",
8
    parameters: {
9
      path: "webhooks/{{provider}}",
10
      httpMethod: ["POST", "GET"],
11
      responseMode: "onReceived",
12
      options: {
13
        rawBody: true // Preserve raw body for signature verification
14
      }
15
    }
16
  },
17

18
  // Provider identification and validation
19
  validator: {
20
    type: "n8n-nodes-base.function",
21
    code: `
22
      const provider = $json.params.provider;
23
      const headers = $json.headers;
24
      const body = $json.body;
25

26
      // Provider-specific validation
27
      const validators = {
28
        stripe: (headers, body) => {
29
          const signature = headers['stripe-signature'];
30
          const secret = $credentials.stripeWebhookSecret;
31

32
          // Verify Stripe signature
33
          const crypto = require('crypto');
34
          const timestamp = signature.split(',')[0].split('=')[1];
35
          const sig = signature.split(',')[1].split('=')[1];
36

37
          const payload = timestamp + '.' + JSON.stringify(body);
38
          const expectedSig = crypto
39
            .createHmac('sha256', secret)
40
            .update(payload)
41
            .digest('hex');
42

43
          return sig === expectedSig;
44
        },
45

46
        github: (headers, body) => {
47
          const signature = headers['x-hub-signature-256'];
48
          const secret = $credentials.githubWebhookSecret;
49

50
          const crypto = require('crypto');
51
          const expectedSig = 'sha256=' + crypto
52
            .createHmac('sha256', secret)
53
            .update(JSON.stringify(body))
54
            .digest('hex');
55

56
          return signature === expectedSig;
57
        },
58

59
        shopify: (headers, body) => {
60
          const hmac = headers['x-shopify-hmac-sha256'];
61
          const secret = $credentials.shopifyWebhookSecret;
62

63
          const crypto = require('crypto');
64
          const hash = crypto
65
            .createHmac('sha256', secret)
66
            .update(JSON.stringify(body), 'utf8')
67
            .digest('base64');
68

69
          return hmac === hash;
70
        }
71
      };
72

73
      // Validate webhook
74
      const validator = validators[provider];
75
      if (!validator) {
76
        throw new Error(\`Unknown provider: \${provider}\`);
77
      }
78

79
      const isValid = validator(headers, body);
80
      if (!isValid) {
81
        throw new Error('Invalid webhook signature');
82
      }
83

84
      // Extract event type
85
      const eventTypes = {
86
        stripe: () => body.type,
87
        github: () => headers['x-github-event'],
88
        shopify: () => headers['x-shopify-topic']
89
      };
90

91
      const eventType = eventTypes[provider]();
92

93
      return [{
94
        json: {
95
          provider,
96
          eventType,
97
          data: body,
98
          validated: true,
99
          timestamp: new Date().toISOString()
100
        }
101
      }];
102
    `
103
  },
104

105
  // Event router
106
  router: {
107
    type: "n8n-nodes-base.switch",
108
    parameters: {
109
      dataType: "expression",
110
      value1: "={{$json.provider}}_{{$json.eventType}}",
111
      rules: [
112
        {
113
          value2: "stripe_payment_intent.succeeded",
114
          output: "processPayment"
115
        },
116
        {
117
          value2: "github_push",
118
          output: "deployCode"
119
        },
120
        {
121
          value2: "shopify_orders/create",
122
          output: "fulfillOrder"
123
        }
124
      ]
125
    }
126
  }
127
};

API Rate Limiting and Throttling#

Example 6: Intelligent Rate Limit Management#

Scenario: Manage API rate limits across multiple services with automatic throttling and retry logic.

1
// Rate Limit Manager
2
const rateLimitManager = {
3
  name: "API Rate Limit Handler",
4

5
  // Rate limit tracker
6
  tracker: {
7
    type: "n8n-nodes-base.function",
8
    code: `
9
      // Initialize or get rate limit data
10
      let rateLimits = await $getWorkflowStaticData('rateLimits') || {};
11

12
      const api = $json.api;
13
      const now = Date.now();
14

15
      // API rate limit configurations
16
      const limits = {
17
        twitter: { calls: 300, window: 900000 }, // 300 calls per 15 minutes
18
        github: { calls: 5000, window: 3600000 }, // 5000 calls per hour
19
        stripe: { calls: 100, window: 1000 }, // 100 calls per second
20
        salesforce: { calls: 15000, window: 86400000 } // 15000 calls per day
21
      };
22

23
      // Initialize API limits if not exists
24
      if (!rateLimits[api]) {
25
        rateLimits[api] = {
26
          calls: [],
27
          nextReset: now + limits[api].window
28
        };
29
      }
30

31
      // Clean old calls
32
      const windowStart = now - limits[api].window;
33
      rateLimits[api].calls = rateLimits[api].calls.filter(
34
        timestamp => timestamp > windowStart
35
      );
36

37
      // Check if we can make a call
38
      const currentCalls = rateLimits[api].calls.length;
39
      const maxCalls = limits[api].calls;
40

41
      if (currentCalls >= maxCalls) {
42
        // Calculate wait time
43
        const oldestCall = rateLimits[api].calls[0];
44
        const waitTime = (oldestCall + limits[api].window) - now;
45

46
        return [{
47
          json: {
48
            canProceed: false,
49
            waitTime: waitTime,
50
            currentCalls: currentCalls,
51
            maxCalls: maxCalls,
52
            api: api
53
          }
54
        }];
55
      }
56

57
      // Record the call
58
      rateLimits[api].calls.push(now);
59
      await $setWorkflowStaticData('rateLimits', rateLimits);
60

61
      return [{
62
        json: {
63
          canProceed: true,
64
          currentCalls: currentCalls + 1,
65
          maxCalls: maxCalls,
66
          remainingCalls: maxCalls - (currentCalls + 1),
67
          api: api
68
        }
69
      }];
70
    `
71
  },
72

73
  // Adaptive throttler
74
  throttler: {
75
    type: "n8n-nodes-base.if",
76
    parameters: {
77
      conditions: {
78
        boolean: [
79
          {
80
            value1: "={{$json.canProceed}}",
81
            value2: true
82
          }
83
        ]
84
      }
85
    }
86
  },
87

88
  // Wait node for rate limiting
89
  waiter: {
90
    type: "n8n-nodes-base.wait",
91
    parameters: {
92
      resume: "timeInterval",
93
      options: {
94
        unit: "milliseconds",
95
        value: "={{$json.waitTime}}"
96
      }
97
    }
98
  },
99

100
  // Batch processor for efficient API usage
101
  batchProcessor: {
102
    type: "n8n-nodes-base.function",
103
    code: `
104
      // Group items for batch processing
105
      const batchSize = 100; // Adjust based on API limits
106
      const items = $input.all();
107
      const batches = [];
108

109
      for (let i = 0; i < items.length; i += batchSize) {
110
        batches.push(items.slice(i, i + batchSize));
111
      }
112

113
      // Process batches with delays
114
      const results = [];
115
      for (const [index, batch] of batches.entries()) {
116
        // Add delay between batches
117
        if (index > 0) {
118
          await new Promise(resolve => setTimeout(resolve, 1000));
119
        }
120

121
        // Process batch
122
        const batchData = batch.map(item => item.json);
123
        results.push({
124
          json: {
125
            batchNumber: index + 1,
126
            totalBatches: batches.length,
127
            items: batchData
128
          }
129
        });
130
      }
131

132
      return results;
133
    `
134
  }
135
};

API Data Transformation#

Example 7: Complex Data Transformation Pipeline#

Scenario: Transform data between different API formats (SOAP to REST, XML to JSON).

1
// Data Transformation Pipeline
2
const transformationPipeline = {
3
  name: "API Data Transformer",
4

5
  // SOAP to REST converter
6
  soapConverter: {
7
    type: "n8n-nodes-base.function",
8
    code: `
9
      const soap = require('soap');
10
      const xml2js = require('xml2js');
11

12
      // Parse SOAP response
13
      const soapResponse = $json.soapResponse;
14
      const parser = new xml2js.Parser({
15
        explicitArray: false,
16
        ignoreAttrs: true
17
      });
18

19
      const parsed = await parser.parseStringPromise(soapResponse);
20

21
      // Extract data from SOAP envelope
22
      const body = parsed['soap:Envelope']['soap:Body'];
23
      const data = body[Object.keys(body)[0]];
24

25
      // Transform to REST-friendly format
26
      const restFormat = {
27
        data: normalizeData(data),
28
        metadata: {
29
          source: 'SOAP',
30
          transformed: new Date().toISOString()
31
        }
32
      };
33

34
      function normalizeData(obj) {
35
        if (typeof obj !== 'object') return obj;
36

37
        const normalized = {};
38
        for (const [key, value] of Object.entries(obj)) {
39
          // Convert SOAP naming to REST naming
40
          const restKey = key.replace(/([A-Z])/g, '_$1').toLowerCase();
41
          normalized[restKey] = Array.isArray(value)
42
            ? value.map(normalizeData)
43
            : normalizeData(value);
44
        }
45
        return normalized;
46
      }
47

48
      return [{json: restFormat}];
49
    `
50
  },
51

52
  // Schema mapper
53
  schemaMapper: {
54
    type: "n8n-nodes-base.function",
55
    code: `
56
      // Map between different API schemas
57
      const sourceData = $json;
58
      const mappingRules = {
59
        // Source field -> Target field
60
        'user_id': 'customerId',
61
        'user_name': 'customer.name',
62
        'user_email': 'customer.contact.email',
63
        'order_items': 'lineItems',
64
        'total_amount': 'orderTotal',
65
        'created_date': 'orderDate'
66
      };
67

68
      function mapData(source, rules) {
69
        const target = {};
70

71
        for (const [sourceKey, targetKey] of Object.entries(rules)) {
72
          const value = getNestedValue(source, sourceKey);
73
          if (value !== undefined) {
74
            setNestedValue(target, targetKey, value);
75
          }
76
        }
77

78
        return target;
79
      }
80

81
      function getNestedValue(obj, path) {
82
        return path.split('.').reduce((current, key) =>
83
          current?.[key], obj);
84
      }
85

86
      function setNestedValue(obj, path, value) {
87
        const keys = path.split('.');
88
        const lastKey = keys.pop();
89
        const target = keys.reduce((current, key) => {
90
          if (!current[key]) current[key] = {};
91
          return current[key];
92
        }, obj);
93
        target[lastKey] = value;
94
      }
95

96
      const mapped = mapData(sourceData, mappingRules);
97
      return [{json: mapped}];
98
    `
99
  },
100

101
  // Data validator
102
  validator: {
103
    type: "n8n-nodes-base.function",
104
    code: `
105
      // Validate transformed data against schema
106
      const Ajv = require('ajv');
107
      const ajv = new Ajv();
108

109
      const schema = {
110
        type: 'object',
111
        required: ['customerId', 'customer', 'lineItems', 'orderTotal'],
112
        properties: {
113
          customerId: { type: 'string' },
114
          customer: {
115
            type: 'object',
116
            required: ['name', 'contact'],
117
            properties: {
118
              name: { type: 'string' },
119
              contact: {
120
                type: 'object',
121
                required: ['email'],
122
                properties: {
123
                  email: {
124
                    type: 'string',
125
                    format: 'email'
126
                  }
127
                }
128
              }
129
            }
130
          },
131
          lineItems: {
132
            type: 'array',
133
            items: {
134
              type: 'object',
135
              required: ['productId', 'quantity', 'price'],
136
              properties: {
137
                productId: { type: 'string' },
138
                quantity: { type: 'number', minimum: 1 },
139
                price: { type: 'number', minimum: 0 }
140
              }
141
            }
142
          },
143
          orderTotal: { type: 'number', minimum: 0 },
144
          orderDate: { type: 'string', format: 'date-time' }
145
        }
146
      };
147

148
      const validate = ajv.compile(schema);
149
      const valid = validate($json);
150

151
      if (!valid) {
152
        throw new Error(\`Validation failed: \${JSON.stringify(validate.errors)}\`);
153
      }
154

155
      return [{json: { ...json, validated: true }}];
156
    `
157
  }
158
};

API Pagination Handling#

Example 8: Advanced Pagination Strategies#

Scenario: Handle different pagination styles (cursor, offset, page-based) across various APIs.

1
// Universal Pagination Handler
2
const paginationHandler = {
3
  name: "API Pagination Manager",
4

5
  // Pagination detector
6
  detector: {
7
    type: "n8n-nodes-base.function",
8
    code: `
9
      // Detect pagination type from API response
10
      const response = $json;
11
      const headers = $json.headers;
12

13
      // Check for different pagination indicators
14
      const paginationTypes = {
15
        cursor: () => {
16
          if (response.cursor || response.next_cursor) {
17
            return {
18
              type: 'cursor',
19
              nextCursor: response.cursor || response.next_cursor,
20
              hasMore: response.has_more || !!response.next_cursor
21
            };
22
          }
23
        },
24

25
        link: () => {
26
          const linkHeader = headers?.link;
27
          if (linkHeader) {
28
            const links = parseLinkHeader(linkHeader);
29
            return {
30
              type: 'link',
31
              nextUrl: links.next,
32
              hasMore: !!links.next
33
            };
34
          }
35
        },
36

37
        offset: () => {
38
          if ('offset' in response && 'limit' in response) {
39
            return {
40
              type: 'offset',
41
              offset: response.offset,
42
              limit: response.limit,
43
              total: response.total,
44
              hasMore: response.offset + response.limit < response.total
45
            };
46
          }
47
        },
48

49
        page: () => {
50
          if (response.page !== undefined) {
51
            return {
52
              type: 'page',
53
              currentPage: response.page,
54
              totalPages: response.total_pages,
55
              hasMore: response.page < response.total_pages
56
            };
57
          }
58
        }
59
      };
60

61
      function parseLinkHeader(header) {
62
        const links = {};
63
        header.split(',').forEach(part => {
64
          const section = part.split(';');
65
          const url = section[0].replace(/<(.*)>/, '$1').trim();
66
          const name = section[1].replace(/rel="(.*)"/, '$1').trim();
67
          links[name] = url;
68
        });
69
        return links;
70
      }
71

72
      // Detect pagination type
73
      for (const detector of Object.values(paginationTypes)) {
74
        const result = detector();
75
        if (result) {
76
          return [{json: result}];
77
        }
78
      }
79

80
      // No pagination detected
81
      return [{json: { type: 'none', hasMore: false }}];
82
    `
83
  },
84

85
  // Pagination iterator
86
  iterator: {
87
    type: "n8n-nodes-base.function",
88
    code: `
89
      // Iterate through all pages
90
      const paginationType = $json.type;
91
      const apiEndpoint = $json.endpoint;
92
      let allData = [];
93
      let hasMore = true;
94
      let nextToken = null;
95
      let page = 1;
96
      let offset = 0;
97
      const limit = 100;
98
      const maxPages = 100; // Safety limit
99

100
      while (hasMore && page <= maxPages) {
101
        let requestParams = {};
102

103
        // Build request based on pagination type
104
        switch (paginationType) {
105
          case 'cursor':
106
            if (nextToken) {
107
              requestParams.cursor = nextToken;
108
            }
109
            break;
110

111
          case 'offset':
112
            requestParams.offset = offset;
113
            requestParams.limit = limit;
114
            break;
115

116
          case 'page':
117
            requestParams.page = page;
118
            requestParams.per_page = limit;
119
            break;
120
        }
121

122
        // Make API request
123
        const response = await $http.get(apiEndpoint, {
124
          params: requestParams,
125
          headers: {
126
            'Authorization': \`Bearer \${$credentials.apiToken}\`
127
          }
128
        });
129

130
        // Extract data and pagination info
131
        const data = response.data.items || response.data.data || response.data;
132
        allData.push(...data);
133

134
        // Update pagination variables
135
        switch (paginationType) {
136
          case 'cursor':
137
            nextToken = response.data.next_cursor;
138
            hasMore = !!nextToken;
139
            break;
140

141
          case 'offset':
142
            offset += limit;
143
            hasMore = offset < response.data.total;
144
            break;
145

146
          case 'page':
147
            page++;
148
            hasMore = page <= response.data.total_pages;
149
            break;
150

151
          default:
152
            hasMore = false;
153
        }
154

155
        // Rate limit protection
156
        await new Promise(resolve => setTimeout(resolve, 200));
157
      }
158

159
      return [{
160
        json: {
161
          totalItems: allData.length,
162
          pages: page - 1,
163
          data: allData
164
        }
165
      }];
166
    `
167
  }
168
};

API Error Handling and Recovery#

Example 9: Comprehensive Error Management#

Scenario: Implement robust error handling with retry logic, circuit breakers, and fallback mechanisms.

1
// Error Handling System
2
const errorHandlingSystem = {
3
  name: "API Error Handler",
4

5
  // Circuit breaker implementation
6
  circuitBreaker: {
7
    type: "n8n-nodes-base.function",
8
    code: `
9
      // Circuit breaker for API calls
10
      let circuitState = await $getWorkflowStaticData('circuitBreaker') || {};
11
      const api = $json.api;
12
      const now = Date.now();
13

14
      // Initialize circuit for API if not exists
15
      if (!circuitState[api]) {
16
        circuitState[api] = {
17
          state: 'closed', // closed, open, half-open
18
          failures: 0,
19
          lastFailure: null,
20
          successCount: 0
21
        };
22
      }
23

24
      const circuit = circuitState[api];
25
      const config = {
26
        failureThreshold: 5,
27
        timeout: 60000, // 1 minute
28
        halfOpenRequests: 3
29
      };
30

31
      // Check circuit state
32
      switch (circuit.state) {
33
        case 'open':
34
          // Check if timeout has passed
35
          if (now - circuit.lastFailure > config.timeout) {
36
            circuit.state = 'half-open';
37
            circuit.successCount = 0;
38
          } else {
39
            throw new Error(\`Circuit breaker is open for \${api}\`);
40
          }
41
          break;
42

43
        case 'half-open':
44
          // Allow limited requests
45
          if (circuit.successCount >= config.halfOpenRequests) {
46
            circuit.state = 'closed';
47
            circuit.failures = 0;
48
          }
49
          break;
50
      }
51

52
      try {
53
        // Make API call
54
        const response = await makeApiCall($json);
55

56
        // Record success
57
        circuit.successCount++;
58
        if (circuit.state === 'half-open' &&
59
            circuit.successCount >= config.halfOpenRequests) {
60
          circuit.state = 'closed';
61
          circuit.failures = 0;
62
        }
63

64
        await $setWorkflowStaticData('circuitBreaker', circuitState);
65
        return [{json: response}];
66

67
      } catch (error) {
68
        // Record failure
69
        circuit.failures++;
70
        circuit.lastFailure = now;
71

72
        if (circuit.failures >= config.failureThreshold) {
73
          circuit.state = 'open';
74
        }
75

76
        await $setWorkflowStaticData('circuitBreaker', circuitState);
77
        throw error;
78
      }
79
    `
80
  },
81

82
  // Retry mechanism with exponential backoff
83
  retryHandler: {
84
    type: "n8n-nodes-base.function",
85
    code: `
86
      // Exponential backoff retry logic
87
      const maxRetries = 5;
88
      const baseDelay = 1000; // 1 second
89
      let lastError;
90

91
      for (let attempt = 1; attempt <= maxRetries; attempt++) {
92
        try {
93
          // Attempt API call
94
          const response = await $http.request({
95
            method: $json.method,
96
            url: $json.url,
97
            data: $json.data,
98
            headers: $json.headers,
99
            timeout: 30000
100
          });
101

102
          // Success - return response
103
          return [{
104
            json: {
105
              success: true,
106
              attempt: attempt,
107
              response: response.data
108
            }
109
          }];
110

111
        } catch (error) {
112
          lastError = error;
113

114
          // Check if error is retryable
115
          const retryableErrors = [
116
            'ECONNRESET',
117
            'ETIMEDOUT',
118
            'ENOTFOUND',
119
            'ESOCKETTIMEDOUT'
120
          ];
121

122
          const statusCodes = [408, 429, 500, 502, 503, 504];
123

124
          const isRetryable =
125
            retryableErrors.includes(error.code) ||
126
            statusCodes.includes(error.response?.status);
127

128
          if (!isRetryable || attempt === maxRetries) {
129
            throw error;
130
          }
131

132
          // Calculate delay with jitter
133
          const delay = Math.min(
134
            baseDelay * Math.pow(2, attempt - 1) + Math.random() * 1000,
135
            30000 // Max 30 seconds
136
          );
137

138
          console.log(\`Retry attempt \${attempt} after \${delay}ms\`);
139
          await new Promise(resolve => setTimeout(resolve, delay));
140
        }
141
      }
142

143
      throw lastError;
144
    `
145
  },
146

147
  // Fallback handler
148
  fallbackHandler: {
149
    type: "n8n-nodes-base.function",
150
    code: `
151
      // Implement fallback strategies
152
      const primaryApi = $json.primary;
153
      const fallbacks = $json.fallbacks || [];
154
      const errors = [];
155

156
      // Try primary API
157
      try {
158
        const response = await callApi(primaryApi);
159
        return [{json: { source: 'primary', data: response }}];
160
      } catch (error) {
161
        errors.push({ api: primaryApi.name, error: error.message });
162
      }
163

164
      // Try fallback APIs
165
      for (const fallback of fallbacks) {
166
        try {
167
          const response = await callApi(fallback);
168
          return [{
169
            json: {
170
              source: 'fallback',
171
              fallbackApi: fallback.name,
172
              data: response,
173
              errors: errors
174
            }
175
          }];
176
        } catch (error) {
177
          errors.push({ api: fallback.name, error: error.message });
178
        }
179
      }
180

181
      // All APIs failed - use cache or default
182
      const cachedData = await $getWorkflowStaticData('apiCache');
183
      if (cachedData) {
184
        return [{
185
          json: {
186
            source: 'cache',
187
            data: cachedData,
188
            errors: errors,
189
            cached: true
190
          }
191
        }];
192
      }
193

194
      // Return default/degraded response
195
      return [{
196
        json: {
197
          source: 'default',
198
          data: getDefaultResponse(),
199
          errors: errors,
200
          degraded: true
201
        }
202
      }];
203

204
      async function callApi(config) {
205
        return await $http.request(config);
206
      }
207

208
      function getDefaultResponse() {
209
        return {
210
          message: 'Service temporarily unavailable',
211
          timestamp: new Date().toISOString()
212
        };
213
      }
214
    `
215
  }
216
};

API Monitoring and Analytics#

Example 10: API Performance Monitoring#

Scenario: Track API performance metrics, response times, and error rates.

1
// API Monitoring System
2
const apiMonitoring = {
3
  name: "API Performance Monitor",
4

5
  // Request interceptor
6
  requestMonitor: {
7
    type: "n8n-nodes-base.function",
8
    code: `
9
      // Track API request metrics
10
      const startTime = Date.now();
11
      const request = {
12
        api: $json.api,
13
        endpoint: $json.endpoint,
14
        method: $json.method,
15
        timestamp: new Date().toISOString()
16
      };
17

18
      try {
19
        // Make API call
20
        const response = await $http.request($json);
21
        const endTime = Date.now();
22

23
        // Collect metrics
24
        const metrics = {
25
          ...request,
26
          status: response.status,
27
          duration: endTime - startTime,
28
          size: JSON.stringify(response.data).length,
29
          success: true
30
        };
31

32
        // Store metrics
33
        await storeMetrics(metrics);
34

35
        return [{
36
          json: {
37
            response: response.data,
38
            metrics: metrics
39
          }
40
        }];
41

42
      } catch (error) {
43
        const endTime = Date.now();
44

45
        // Collect error metrics
46
        const metrics = {
47
          ...request,
48
          status: error.response?.status || 0,
49
          duration: endTime - startTime,
50
          error: error.message,
51
          success: false
52
        };
53

54
        // Store metrics
55
        await storeMetrics(metrics);
56

57
        throw error;
58
      }
59

60
      async function storeMetrics(metrics) {
61
        // Get existing metrics
62
        let allMetrics = await $getWorkflowStaticData('apiMetrics') || [];
63

64
        // Add new metrics
65
        allMetrics.push(metrics);
66

67
        // Keep only last 1000 entries
68
        if (allMetrics.length > 1000) {
69
          allMetrics = allMetrics.slice(-1000);
70
        }
71

72
        await $setWorkflowStaticData('apiMetrics', allMetrics);
73
      }
74
    `
75
  },
76

77
  // Analytics calculator
78
  analyticsProcessor: {
79
    type: "n8n-nodes-base.function",
80
    code: `
81
      // Calculate API analytics
82
      const metrics = await $getWorkflowStaticData('apiMetrics') || [];
83
      const now = Date.now();
84
      const timeWindows = {
85
        '1h': 3600000,
86
        '24h': 86400000,
87
        '7d': 604800000
88
      };
89

90
      const analytics = {};
91

92
      for (const [window, duration] of Object.entries(timeWindows)) {
93
        const windowMetrics = metrics.filter(m =>
94
          new Date(m.timestamp).getTime() > now - duration
95
        );
96

97
        if (windowMetrics.length === 0) {
98
          analytics[window] = { noData: true };
99
          continue;
100
        }
101

102
        // Calculate statistics
103
        const successfulRequests = windowMetrics.filter(m => m.success);
104
        const failedRequests = windowMetrics.filter(m => !m.success);
105
        const durations = successfulRequests.map(m => m.duration);
106

107
        analytics[window] = {
108
          totalRequests: windowMetrics.length,
109
          successfulRequests: successfulRequests.length,
110
          failedRequests: failedRequests.length,
111
          successRate: (successfulRequests.length / windowMetrics.length * 100).toFixed(2),
112
          avgResponseTime: durations.length > 0
113
            ? (durations.reduce((a, b) => a + b, 0) / durations.length).toFixed(2)
114
            : 0,
115
          minResponseTime: durations.length > 0 ? Math.min(...durations) : 0,
116
          maxResponseTime: durations.length > 0 ? Math.max(...durations) : 0,
117
          p95ResponseTime: calculatePercentile(durations, 95),
118
          p99ResponseTime: calculatePercentile(durations, 99),
119
          errorTypes: groupErrors(failedRequests),
120
          apiBreakdown: groupByApi(windowMetrics)
121
        };
122
      }
123

124
      function calculatePercentile(arr, percentile) {
125
        if (arr.length === 0) return 0;
126
        const sorted = arr.sort((a, b) => a - b);
127
        const index = Math.ceil((percentile / 100) * sorted.length) - 1;
128
        return sorted[index];
129
      }
130

131
      function groupErrors(failed) {
132
        const errors = {};
133
        failed.forEach(f => {
134
          const status = f.status || 'Unknown';
135
          errors[status] = (errors[status] || 0) + 1;
136
        });
137
        return errors;
138
      }
139

140
      function groupByApi(metrics) {
141
        const apis = {};
142
        metrics.forEach(m => {
143
          if (!apis[m.api]) {
144
            apis[m.api] = {
145
              requests: 0,
146
              avgTime: 0,
147
              errors: 0
148
            };
149
          }
150
          apis[m.api].requests++;
151
          if (!m.success) apis[m.api].errors++;
152
          if (m.duration) {
153
            apis[m.api].avgTime =
154
              (apis[m.api].avgTime * (apis[m.api].requests - 1) + m.duration) /
155
              apis[m.api].requests;
156
          }
157
        });
158
        return apis;
159
      }
160

161
      return [{json: analytics}];
162
    `
163
  },
164

165
  // Alert generator
166
  alertGenerator: {
167
    type: "n8n-nodes-base.function",
168
    code: `
169
      // Generate alerts based on thresholds
170
      const analytics = $json;
171
      const alerts = [];
172

173
      // Define thresholds
174
      const thresholds = {
175
        errorRate: 5, // %
176
        avgResponseTime: 2000, // ms
177
        p95ResponseTime: 5000, // ms
178
        minSuccessRate: 95 // %
179
      };
180

181
      // Check each time window
182
      for (const [window, stats] of Object.entries(analytics)) {
183
        if (stats.noData) continue;
184

185
        // Check error rate
186
        const errorRate = 100 - parseFloat(stats.successRate);
187
        if (errorRate > thresholds.errorRate) {
188
          alerts.push({
189
            severity: 'high',
190
            type: 'error_rate',
191
            message: \`High error rate in \${window}: \${errorRate.toFixed(2)}%\`,
192
            value: errorRate,
193
            threshold: thresholds.errorRate,
194
            window
195
          });
196
        }
197

198
        // Check response time
199
        if (stats.avgResponseTime > thresholds.avgResponseTime) {
200
          alerts.push({
201
            severity: 'medium',
202
            type: 'response_time',
203
            message: \`Slow response time in \${window}: \${stats.avgResponseTime}ms\`,
204
            value: stats.avgResponseTime,
205
            threshold: thresholds.avgResponseTime,
206
            window
207
          });
208
        }
209

210
        // Check p95 response time
211
        if (stats.p95ResponseTime > thresholds.p95ResponseTime) {
212
          alerts.push({
213
            severity: 'medium',
214
            type: 'p95_response_time',
215
            message: \`High p95 response time in \${window}: \${stats.p95ResponseTime}ms\`,
216
            value: stats.p95ResponseTime,
217
            threshold: thresholds.p95ResponseTime,
218
            window
219
          });
220
        }
221
      }
222

223
      return [{
224
        json: {
225
          alerts: alerts,
226
          hasAlerts: alerts.length > 0,
227
          analytics: analytics
228
        }
229
      }];
230
    `
231
  }
232
};

Best Practices for API Integration#

1. Authentication Management#

Store credentials securely using n8n’s credential system
Implement token refresh mechanisms
Use OAuth2 for user-authorized access
Rotate API keys regularly

2. Error Handling#

Implement comprehensive error catching
Use circuit breakers for failing services
Provide meaningful error messages
Log errors for debugging

3. Performance Optimization#

Batch API requests when possible
Implement caching strategies
Use pagination efficiently
Monitor API rate limits

4. Data Validation#

Validate input data before API calls
Verify response data structure
Handle missing or null values
Use schema validation

5. Security Considerations#

Never expose API keys in workflows
Validate webhook signatures
Implement request throttling
Use HTTPS for all API calls

Conclusion#

n8n provides a comprehensive platform for API integration, offering flexibility and power to connect any service. By leveraging its built-in nodes, custom functions, and error handling capabilities, you can build robust API integration workflows that scale with your needs.

The examples and patterns presented in this guide demonstrate the versatility of n8n in handling various API integration scenarios. From simple REST calls to complex GraphQL queries, webhook processing to rate limit management, n8n empowers you to create sophisticated integrations without extensive coding.

Remember to follow best practices, implement proper error handling, and monitor your API integrations to ensure reliable and efficient operation. With n8n, you have the tools to build enterprise-grade API integrations that drive your business forward.