You found the perfect API for your workflow. You open the documentation and... it's a mess. Endpoints are wrong. Examples are outdated. Authentication is explained in three contradictory ways.
Welcome to the real world of API integration.
Here's the skill nobody teaches: how to connect to any API, even when the docs are useless.
Why API Documentation Is Usually Bad
Before we fix this, understand why it happens:
Docs are written by developers who built the API. They know so much context that they skip "obvious" things. What's obvious to them is confusing to everyone else.
Docs go stale. The API evolves, but updating documentation isn't exciting work. So it doesn't happen.
Docs are written for ideal cases. Real-world edge cases, error handling, and authentication quirks are glossed over.
This isn't a complaint — it's reality. The faster you accept that docs are a starting point, not a complete guide, the faster you'll become effective.
The Detective's Toolkit
Before you start, gather your tools:
1. Browser Developer Tools
Your browser's Network tab is your best friend. It shows you exactly what requests are being made when you use a service's web interface.
How to use it:
- Open the service's web app
- Open Developer Tools (F12 or Cmd+Option+I)
- Go to the Network tab
- Perform the action you want to automate
- Look at the requests that fire
You'll see the exact endpoints, headers, and payloads that work.
2. Postman or Insomnia
Before building in n8n, test your API calls in a dedicated tool. It's faster to iterate and easier to debug.
Why this helps:
- Isolate API issues from n8n issues
- Save working requests for reference
- Generate code snippets
3. The HTTP Request Node
n8n's HTTP Request node is your Swiss Army knife. When there's no dedicated node for a service, this is how you connect.
Step-by-Step: Connecting an Undocumented API
Let's walk through a real scenario.
Step 1: Find Any Working Request
Start with the web interface. Every web app is just making API calls under the hood.
In the Network tab, look for:
- XHR/Fetch requests (filter to see only API calls)
- Requests to /api/ endpoints
- JSON responses
Copy these details:
- Full URL (including query parameters)
- HTTP method (GET, POST, etc.)
- Headers (especially Authorization, Content-Type)
- Request body (for POST/PUT requests)
Step 2: Reproduce in Postman
Take what you found and recreate it:
- Create a new request
- Set the method and URL
- Add headers exactly as you saw them
- Add the body if needed
- Send it
If it works: You've found your endpoint. Document it.
If it fails: Check authentication. The token you copied might be session-specific.
Step 3: Figure Out Authentication
This is where most people get stuck. Common patterns:
API Key in Header:
```
Authorization: Bearer your-api-key
X-API-Key: your-api-key
```
API Key in Query String:
```
https://api.service.com/endpoint?api_key=your-key
```
Basic Auth:
```
Authorization: Basic base64(username:password)
```
OAuth 2.0:
More complex. You'll need to get a token first, then use it.
Where to find your API key:
- Account settings
- Developer settings
- API section
- Integrations page
If you can't find it, the service might not have a public API. Check if they have a developer program you need to sign up for.
Step 4: Build in n8n
Now translate your working Postman request to n8n:
HTTP Request node settings:
- Method: Match what worked in Postman
- URL: The full endpoint URL
- Authentication: Use the appropriate type
- Headers: Add any custom headers you needed
- Body: For POST/PUT, add your JSON
Pro tip: Use n8n's "Import cURL" feature. In Postman, copy your request as cURL, then paste it into the HTTP Request node.
Step 5: Handle the Response
APIs return data in different structures. Common patterns:
Data in root:
```
{{ $json.id }}
{{ $json.name }}
```
Data nested in response:
```
{{ $json.data.id }}
{{ $json.response.results[0].name }}
```
Paginated results:
```
{{ $json.items }}
{{ $json.next_page_token }}
```
Use the output panel in n8n to explore the actual structure.
Common Problems and Fixes
"401 Unauthorized"
Check:
- Is your API key correct?
- Is the header name right? (Authorization vs X-API-Key vs Api-Key)
- Does the key need a prefix? (Bearer, Basic, Token)
- Has the key expired?
"403 Forbidden"
Check:
- Do you have permission for this endpoint?
- Is your API plan limited? (free tier restrictions)
- Are you hitting rate limits?
- Is there IP whitelisting?
"404 Not Found"
Check:
- Is the URL exactly right? (trailing slashes matter)
- Is the endpoint deprecated?
- Are you using the right API version?
"CORS Error" (in browser testing)
This won't affect n8n (server-side requests don't have CORS). But if you see it in browser tools, the endpoint still works — just test it in Postman instead.
"SSL Certificate Error"
In n8n: You can disable SSL verification in the HTTP Request node under Options. Not recommended for production, but useful for testing.
Advanced Techniques
Reverse-Engineering from Mobile Apps
Mobile apps also make API calls. Tools like Charles Proxy or mitmproxy can intercept them. This is more advanced but useful when there's no web interface.
Reading Source Code
If the service has open-source clients or SDKs, read them. The code shows exactly how authentication and requests work.
Using GraphQL Introspection
GraphQL APIs often have introspection enabled. You can query them to discover available operations:
```
{
__schema {
types {
name
fields {
name
}
}
}
}
```
Checking the Wayback Machine
Old documentation is sometimes better than current documentation. If docs were rewritten and got worse, find the old version.
Building Robust Integrations
Once you have a working connection, make it production-ready:
Add Error Handling
APIs fail. Handle it gracefully:
- Use the Error Trigger node
- Add retry logic for transient failures
- Log errors for debugging
Respect Rate Limits
Most APIs have limits. Don't hit them:
- Add delays between requests (Wait node)
- Use Split In Batches for bulk operations
- Cache responses when possible
Plan for API Changes
APIs evolve. Protect yourself:
- Don't rely on undocumented fields
- Test your workflows regularly
- Subscribe to the API's changelog or status page
When to Give Up
Sometimes the API just doesn't support what you need. Signs to stop:
- The endpoint requires permissions you can't get
- The API is deprecated with no replacement
- Rate limits make your use case impossible
- The data you need isn't exposed
In these cases, look for alternatives:
- Different APIs that provide similar data
- Webhooks instead of polling
- Scraping (as a last resort, with caution)
- Direct database access (if you control both systems)
Ready to practice API integration? Nodox.ai challenges throw you into real integration scenarios — messy data, tricky authentication, and edge cases that build real skills.